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AC's publications have always been innovative and complete. With the Premiere issue of Amazing 
Computing in February 1986, we introduced the first monthly magazine dedicated to the Amiga. AC's 
commitment to deliver solid information and valuable insight for the Amiga continues today. AC remains 
the first in news coverage — often providing complete stories and pictures of fast-breaking Amiga events in 
the next issue. AC is a forerunner in providing a well balanced mix of reviews, tutorials, tips, programming 
tasks, hardware projects, and more. Each issue of Amazing Computing For The Commodore Amiga is 
packed with the best of the Amiga. 



AC's TECH For The Commodore AMIGA is the first and largest publication dedicated to the technical 
promise of the Amiga. Each quarterly issue provides new frontiers for the Amiga user eager to do more. 
AC's TECH not only attempts to define what the Amiga can do, but expands those boundaries. 



AC's GUIDE To The Commodore AMIGA is the first and only complete guide to the Commodore Amiga. 
AC's GUIDE is the one resource used by the entire Amiga industry for Amiga product information. Yet AC's 
GUIDE also offers a listing of freely redistributable software and a growing registry of Amiga user's groups. 
AC's GUIDE is the complete resource to the expanding platform of Amiga products and services. 

If you are not an AC subscriber, you don't know what you're missing. AC's publications are produced to 
give you more choices and resources. AC makes sure that whatever is happening in the Amiga market, 
you'll know about it. 
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printf ("Hello") ; 



print "Hello" 



JSR printMsg 



say "Hello" 



writeln( "Hello") 
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Macro Disassembler 

Resource is an intelligent interactive disassembler for the Amiga programmer. Full use is made of the Amiga windowing environment and over 
700 functions to make disassembling code easier than its ever been. Resource wil! enable you to explore the Amiga. Find out how your 
favorite program works. Fix bugs in executables. Examine your own compiled code. 

Resource will load/save any file, read disk tracks, or disassemble directly from memory. Virtually all Amiga symbol bases are available at the 
touch of a key. In addition, you may create your own symbol bases. Base-relative addressing is supported for disassembling C programs. 
All Amiga hunk types are supported for code scan. Display is incredibly fast. 

Resource now has a big brother. Like the original program, ReSource'030 will tear apart your code like no other program. And il will do so 
even faster now, because ReSource'030 is written in native MC68030 code. ReSource'030 also understands 68030 instructions. 

ReSource'030 supports the new M68000 Family assembly language syntax specified by Motorola to support the new addressing modes used 
on the 68020/030 processors. ReSource'030 and Macro68 are among the few Amiga programs now available that provide this support. 

Due to popular demand, we now offer ReSource'068. Functionally identical to ReSource'030, this program will run on a 68000 cpu. 
ReSource'Q68 is included when you purchase ReSource'030. 

"If you're serious about disassembling code, look no further!" 

Resource outputs old-syntax source, and will run on any 68K family cpu. ReSource'030 outputs new-syntax source, and requires a 68020/030 cpu. 
ReSource'068 outputs new-syntax source, and will run on any 68K family cpu. Both versions of Resource require at least 1 meg of ram. 

Suggested retail prices: Original Resource, USS95; ReSource'030, USS150 






Macro Assembler 

Macro68 is a powerful new assembler for the entire line of Amiga personal computers. 

Macro68 supports the entire Motorola M68000 Family including the MC68030 and MC68040 CPUs, MC68882 FPU and MC68851 MMU. 
The Amiga Copper is supported also. 

This fast, multi-pass assembler supports the new Motorola M68000 Family assembly language syntax, and comes with a utility to convert 
old-style syntax source code painlessly. The new syntax was developed by Motorola specifically to support the addressing capabilities of the 
new generation of CPUs. Old-style syntax is also supported, at slightly reduced assembly speeds. 

Most features of Macro68 are limited only by available memory. It also boasts macro power unparalleled in products of this class. There are 
many new and innovative assembler directives. For instance, a special structure offset directive assures maximum compatibility with the Amiga's 
interface conventions. Listing control including cross-referencing is included. A user-accessible file provides the ability to customize directives 
and run-time messages from the assembler. 

Macro68 is fully re-entrant, and may be made resident. An AREXX(tm) interface provides "real-time" communication with the editor of your choice. 
A number of directives enable Macro68 to communicate with AmigaDos(tm). External programs may be invoked on either pass, and the results 
interpreted. Possibly the most unique feature of Macro68 is the use of a shared-library, which allows resident preassembled include files for 
incredibly fast assemblies. 

Macro68 is compatible with the directives used by most popular assemblers. Output file formats include executable object, linkable object, 
binary image, and Motorola S records. Macro68 requires at least 1 meg of memory, 

Suggested retail price: USS150 
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Opportunity Knocking 

AC's TECH is designed to educate, promote new 
technologies, and encourage the exchange of ideas in Amiga 
computing. As such, it is a rallying point for Amiga develop- 
ment. Professional Amiga developers and weekend program- 
mers alike have experienced the thrill of a completed project. 
We know what it means to create a program or build a piece of 
hardware. On this basis, I would like our readers to consider 
focusing their talents on creating Amiga products. 

If you have ever had the desire to program a new 
product or create a piece of hardware for the Amiga, now is 
the time. There has never been such an opportunity to excel in 
the marketplace. Not only is Commodore more committed 
than ever to seeing that the Amiga is accepted as a professional 
machine, but there is now an entirely new market in CDTV. 

Yes, Commodore Is Marketing 

Commodore's efforts in marketing have never 
received great praise from Amiga users. Many of us believe 
that Commodore could have done more to position the Amiga 
in the U.S. market. However, CBM has made a new commit- 
ment to carry the Amiga and CDTV into mainstream use. 

CommodoreExpress is CBM's year-old program for 
Amiga 500 users. If your A500 fails and a call to CBM does not 
provide a remedy to the problem, Federal Express will pick up 
the machine at your home or office. It will be repaired and 
returned within three days (just remember to keep your 
original packing material). Tints program will also be available 
to CDTV users. 

Also available under CommodoreExpress is the Gold 
Card Service program for Amiga 2000 and Amiga 3000 
owners. Commodore will provide a one year warranty with 
on-site service for these professional Amiga systems. There is 
also an option to purchase an additional one to two years of 
on-site service. The additional confidence these programs can 
provide for anyone on a tight schedule is priceless. 

In addition, CBM has initiated a leasing program for 
the Amiga. Through Commodore's lease arrangement, most 
businesses will find it easy to incorporate Amigas into their 
facilities. 

In order to use the service and customer satisfaction 
programs, Commodore must attract the customer. Commo- 
dore will concentrate on print media with specially focused 



Amiga and CDTV advertisements to run in six national 
magazines, such as People and Newsweek, this fall. There will 
also be spot television advertisements. 

Included in a brochure supplied by Commodore are a 
few examples of the proposed advertisements. Commodore 
appears to be aggressively pushing the Amiga into the home 
education market, with particular emphasis being placed on 
the use of computers by children. 

What does it all mean? Commodore is going to do 
what we have always asked them to do. They are going to sell 
Amigas. And, although there is a wide assortment of software 
and hardware currently available for the machine, there is 
more to be done. 

Enter CDTV 

Not excited yet? Think about CDTV. CDTV is a brand 
new market based on the Amiga technology. Almost all the 
tools available to program and create on the Amiga will work 
for CDTV. It also offers software developers a world of options 
from sound to graphics. 

We always knew we could tap the CD in CDTV for 
great sound quality. Mow Commodore has released CDX1 , 
which allows a software developer to pull full-motion video 
from the CD into a screen one-third the size of the normal 
display in real time. This is now accessible to CDTV develop- 
ers for use in games, educational software, or any area where 
full-motion video can be an asset. 

As CDTV matures and sales increase, there will be a 
large block of consumers hungry for good software and 
hardware. The people who have a responsibility in securing 
this market are the Amiga product designers. With 540 
megabytes of storage and an entire world of ideas to explore, 
CDTV offers an opportunity that has never been seen before. 
Add to this Commodore's commitment to make CDTV a 
standard and the possibilities are endless. 

Yes, .AC's TECH is supposed to excite you into the 
possibilities of creating on the Amiga. But with all of this 
currently available, our job is extremely easy. 



Sincerely, 




Ernest P. Viveiros, Jr 
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Collectible Disks! 

The Fred Fish Collection 



Choose from the entire Fred Fish collection and get your disks 
quickly and easily by using our toll free number: 1-800-345-3360. 

Our collection is updated constantly so that we may offer you the 
best and most complete selection of Fred Fish disks anywhere. 

Mow Almost 500 Disks! 



Disk prices for AC'S TECH subscribers: 

1 to 9 disks - $6.00 each 

10 to 49 disks - $5.00 each 

50 to 99 disks - $4.00 each 

1 00 disks or more - $3.00 each 

(Disks are S7.00 each for non-subscribers) 

You are protected by our no-hassle, 
defective disk return policy* 

To get FAST SERVICE on Fred Fish disks, use your Visa or MasterCard and 

call 1-800-345-3360. 

Or, just fill out the order form on inside back cover. 

AC'S rECHwarrantiesalldisks for 90days.Noadditionalchargelorpostageandhandlingondiskorders. AC'S FECHissuesMr. Fred Fisha 
royaltyonall drsksalesto encourage the leading Amiga program anthoJogisttocontinuehis outstanding work. 
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SOME WORDS OF PRAISE FOR BASIC AND THE AMIGA 



Dear AC'S TECH: 

The April 1991 issue of BYTE magazine has given some 
noteworthy recognition to both the Amiga and BASIC as an 
environment for learning and experimenting in computer 
science. The article "A Fast, Easy Sort", by Stephen Lacey and 
Richard Box, presents a sorting technique called "Combsort", 
an alternative to the much known, intuitive, but incredibly 
slow, bubble sort. The authors did their work on an Amiga 
2000! Their sorting algorithm is very well described and I 
recommend the article to programming enthusiasts of all 
levels. Example code is given as a single subroutine in both C 
and True BASIC. To experiment with it I had to design my 
own driver program. 

True BASIC is an integrated environment from Kemeny 
and Kurtz, the original inventors of BASIC at Dartmouth 
College in New Hampshire. It is a fully structured high level 
language (like C and Pascal) that is both powerful and easy to 
use. True BASIC programs are completely transportable 
(including graphics!) to four different microcomputers, as well 
as a number of others in the mini and mainframe class. I 
routinely develop programs on my IBM and execute them on 
my Amiga, and visa versa. 

On the magazine diskette (this issue) you will find 
programs that demonstrate the above mentioned Combsort 
subroutine, as well as its Bubble Sort equivalent, in three 
different languages: AmigaBASIC, True BASIC, and finally 
SAS/C. (Note that both AmigaBASIC and True BASIC do not 
yet execute properly on a 32 bit machine, although I hear that 
True BASIC will be upgrading to do that very soon) My 
programs take the BYTE magazine article one step further and 
generate a graphic representation of the program's execution. 
Initially, a low resolution screen is filled with dots representing 
320 randomly chosen numbers (312 in AmigaBASIC, crazy 
eh?). Then the program arranges them in ascending order, 
resulting in a rising graph of sorted values. It is instructional to 
watch the computer slowly sort out the numbers before your 
eyes. For the C and True BASIC versions I have included the 
corresponding stand alone (compiled and linked) programs, 
allowing you to execute them even if you do not own either 
language. 

These programs provide an excellent example of the 
comparative advantages of the three development environ- 
ments for doing investigative work in computer science on the 
Amiga. Although the C version is faster than both versions of 
BASIC, it requires that the programmer be familiar with many 
system dependant details, and is perhaps beyond the level of 
the average computer hobbyist. Check out the code yourself. 



The AmigaBASIC version shows a big reduction in complexity, 
but it has structural limitations due to the fact that external 
subroutines cannot be called by other external subroutines. 
This limits how well you can structure programs, affecting 
their readibility. Also, AmigaBASIC does not support screen 
scaling. Vertical pixel numbers are upside down, increasing 
from top to bottom, rather than the normal bottom to top of 
Cartesian Coordinates (or world coordinates, as we say in 
computer science). I compensate for this by including a user 
defined, vertical screen scaling function. Horizontal scaling is 
not required in this particular example, but to be fair 1 should 
point out that most graphic programs would require it. 

All three programs were designed using the most similar 
hierarchical structure possible in each language. External 
subroutines (separate fragments having their own local 
variables) were used in both versions of BASIC in order that 
they more closely resemble their C counterpart, which treats all 
functions as external. True BASIC demonstrates itself as the 
most readable (pseudocode-like), shows no structural limita- 
tions, and is reasonably fast. 



LANGUAGE 

AmigaBASIC 
True BASIC 
C 



BUBBLE SORT 

21 min, 34 sec 
11 min, 22 sec 
min, 45 sec 



COMBSORT 

1 min. 10 sec 
min, 30 sec 
min, 2 sec 



Note that these programs do not represent a 100% accurate 
comparison because of the time required for the system to 
write pixels every time a swap occurs. If you want to make 
your own accurate measurements of this sorting method you 
should use the straight sorting code from the original article. 
Still, these graphic versions are accurate enough for instruc- 
tional purposes, and they are fun to look at. 

I was happy to see such an article. A certain number of us 
have purchased our Amigas in order to leam and experiment 
with programming, and BASIC does indeed plav a large role in 
that. I encourage similar articles here in AC's TECH/ AMIGA. 
— Paul Castonguay 



Send your questions and comments to: 

ACs TECH MessagePort 

P.O. Box 869 

Fall River, MA 02722-0869 

Rentiers whose letters are published will receive five public domain disks free of 
charge. (All letter become the property ofP.i.M. Publications, Inc. The AC s 
TECH editors reserve the right to edit all letters for length and clarity.) 
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The Complete Amazing Computing library 

which now includes Volume 5 

is available at incredible savings of 50% off! 

♦ Volume 1 is now available for just $19.95*! ♦ 

(A $45.00 cover price value, the first year of AC includes 9 info-packed issues.) 

♦ Volumes 2, 3, 4, & 5 are now priced at just $29.95* each! ♦ 

(Volumes 2,3, & 4 include 12 issues each, and are cover priced at $60,00 per volume set.) 



Subscribers can purchase freely redistributable disks** at 
This unbeatable offer includes all Fred Fish, AMICUS, and 

AC disks 



Pricing for subscribers is as follows: 

♦ 1 to 9 disks: $6.00 each 

♦ 1 to 49 disks: $5.00 each 

♦ 50 to 99 disks: $4.00 each 

♦ 100 disks or more: $3.00 each 

(Disks are priced at $7.00 each and are not discounted for non-subscribers) 

To get FAST SERVICE on volume set orders, freely 

redistributable disks, 

call 1-800-345-3360 



" Postage & handling for each volume is S4.00 in the U.S., S7.50 for surface in Canada and Mexico, and $10.00 for all other foreign surface. 

" AC warranties all disks lor 90 days. No additional charge for postage and handling on disk orders. AC issues Mr. Fred Fish a royalty on all disk sales to encourage 

the leading Amiga program anthologist to continue his outstanding work. 




design 



Press the right mouse button — a menu pops up. Select an action com- 
mand from the menu, move the mouse cursor over an object and press the 
left mouse button — the object changes color. Move the mouse again — the 
object moves, changes size, or rotates as the mouse moves. Press the left 
mouse button a second time — the highlighted object is erased and redrawn 
at its new location, size, or orientation. What was just described is a 
"point, click, and drag" metaphor used in modern CAD systems for 
translating, scaling, and rotating geometric objects. This segment of the 
series shows how to implement the point, click, and drag" metaphor when 
designing Amiga CAD applications 



Introduction 

How does a CAD program tell 
which object a user picked when a mouse 
button is pressed? How are mouse move- 
ments in pixel coordinates converted into 
world coordinate translations, scale val- 
ues, or rotation angles? [n this article, 
we'll see how CAD programs do all these 
things and more, and develop procedures 
to implement the metaphor just described, 
We'll also develop procedures for "pan- 
ning" a drawing which is too large to fit in 
a window, and "zoom in" to reveal small 
drawing details or "zoom out" to show a 
bigger view of the drawing. The proce- 
dures will then be put to work in an event- 
driven program which will let us move, 
resize, and rotate objects, or pan and zoom 
our model world using just the mouse. 



Actions, Objects, and Modifiers 

When we are interacting with a 
program, we are telling the program what 
is to be done and which objects are to act 
or be acted upon. We are giving the pro- 
gram, or objects in the program, com- 
mands. Since natural language sentences 
are constructed from nouns and verbs, an 
effective way to allow a user to input 
program commands is with sentence frag- 
ments containing nouns and verbs. The 
verbs describe program actions, and the 
nouns describe the objects which are to be 
manipulated. The sentence fragments can 
take one of two forms: either "action-ob- 
ject" sentences, or "object-action" sen- 
tences. Commandscan also contain object 
modifiers, action modifiers, or both. As an 
example, a typical command for deleting 



all lines in a drawing program might be 
either "Delete-all-lines," or "line-delete - 
all." The action is "delete," the objects are 
"lines," and the modifier is "all." Many 
commands don't require that an object be 
specified: theobject is assumed to be what- 
ever object has already been selected, or 
assumed to be the next object which will 
be selected. These types of commands 
require two user actions. The user selects 
an object and then an action (pre-select 
mode), or selects an action and then an 
object (post-select mode). Many com- 
mands don't require any object specifiers 
at all. "Quit," "Save," and "Delete-All" 
are examples. These are "immediate 
mode" commands, and require only a 
single user action. 

Intuition and other graphical in- 
terfaces provide tools which can be used 
toelicit user commands. Theprimary tools 
are menus, gadgets, requesters, and point- 
ing devices. When we write interactive 
programs, we have to decide what com- 
mands our programs will recognize, then 
match the commands to the graphical in- 
terface tools which are available to us. 
Sometimes, an entire command can be 
mapped to a single tool (a window "close" 
gadget, for example), but many times, we 
have to break a command into parts and 
match the parts to different interface tools. 
When we break a command into parts, 
our program has to put the parts back 
together before it can make sense of the 
command. 
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PART II— INTUITION EVENTS AND 
USER INTERACTION 




BY FOREST W. ARNOLD 



Interactive tools such as menus 
and gadgets let us write programs which 
are simple to use (if the interface is well 
designed). However, these sametools also 
increase the complexity of a program's 
code. When a user picks a menu item, 
Intuition doesn't send our programs what- 
ever command the menu item represents. 
Instead, Intuition sends us a MENUPICK 
event, and our program has to figure out 
which menu item was picked, and then 
figure out what command the menu item 
represents. To manage this task, we need 
general -purpose techniques for receiving 
and processing commands through input 
events which will make our program code 
as simple as possible. 

Event Driven Programming 

If an Intuition window is opened 
with one or more IDCMP flags set, Intu- 
ition automatically creates an "Intuition 
Direct Communication Message Port" for 
the window, and as input events occur, 
places event messagesinaqueue attached 
to the message port. Input events can be 
generated by a program user with the 
mouse or the keyboard. They can also be 
generated by other applications, or by 
devices such as the trackdisk device or 
timer device. Programs which receive in- 
put through the IDCMP "wait" until noti- 
fied that an event message lias arrived, 
read the message, perform whatever ac- 
tion is appropriate, and reply to the mes- 
sage. Programs which wait for an event to 
occur before "doing something," and 
which only do something when an event 
occurs, are called event-driven programs. 

The process of just responding 
to input events seems simple. Many times 
itis,butmostofthetimeit'snot. There a re 
two reasons why event-driven programs 



can be complicated. First, interactive pro- 
grams can't usually determine or predict 
the order in which input events will ar- 
rive. Users, especially inexperienced ones, 
don't always do things in the order pro- 
grammers expect them to. Second, most 
non-trivial program actions require a se- 
quence of events to occur before a pro- 
gram can determine what needs to be 
done and to gather the information needed 
to do it. As an example, before an object 
can be moved in our demonstration pro- 
gram, several related events have to occur 
in sequence. The "move" action needs to 
be specified with a menu pick, the object 
to be moved must be picked with the 
mouse select button, and the move values 
need to be obtained by tracking the posi- 
tion of the mouse until a second select 
button press occurs. An object can not be 
moved until all of these events have oc- 
curred . The program code requ i red to take 
care of unexpected events and to keep up 
with a series of related events can quickly 
become complex and unmanageable. 

Fortunately, the complexity of 
event-driven programs can be reduced 
through the use of "event handlers" and 
"sta te vectors. "State vectors are d a ta stru c- 
tures used to keep up with the current 
state of a program and its data. Event 
handlers are procedures which are called 
when a specific event or class of events 



Definition of the Extension Structure 



ypedef int (* event Proc_t] (struct IntuiMessage *,void *); 

typedef struct _intuiExtension 

( 
event?roc_t handler; /* pointer to event handler */ 
void *data; /* arg for event handler */ 

} intuiExtension_t ; 



occurs. Event handlers are simple proce- 
dures which only do one of two things: 
they either directly perform an action, or 
they modify a program's state. Actions, in 
turn, usually modify an event-driven 
program's state, and state changes may 
also trigger actions. Most event handlers 
which modify a program's state generally 
evaluate the new state to determine if an 
action should be triggered. 

When event handlers and state 
vectors are used, program logic is moved 
out of a program's input code and distrib- 
uted among its event handler procedures. 
The top-level input logic for event-driven 
programs is simple: the input code just 
calls an event handler and sends it what- 
ever da ta it needs. The algorithm we'll use 
for receiving and dispatching input events 



Receive an event 
Retrieve the event handler 
which will process the event 

Retrieve the data needed 
by the event handler 
Call the event handler, 



sending it the data it needs 
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To implement this algorithm, we need to associate event 
handlers and their data with input events. The simplest way to do 
this is with a structure containing pointers. We'll define an 
"Intuition extension" structure to hold both a function pointer to 
an event handler and a pointer to the handler's data. Our exten- 
sion structure will then be attached to whatever Intuition object 
which generates events that the handler is responsible for pro- 
cessing. The definition of the extension structure we'll use (we 
also define a type for event handler function pointers to make 
casting the pointers easier) is shown on page 9. 

When an event arrives, the input handler retrieves the 
extension structure, gets the pointer to the event handler and the 
pointer to the handler's data, and calls the event handler using the 



Table One 

Demonstration CAD Program Commands 

Command Syntax Mode 


Quit project 


Action 


Immediate 


Select an object 


Action - object 


Immediate 


Drag an object 


Action - object 


immediate 


Move an object 


Action - object 


Post-select 


Size an object 


Action ■ object 


Post-select 


Rotate an object 


Action - object 


Post-select 


View - All 


Object - action 


Immediate 


View - Zoom - In 


Object - action 


Immediate 


View - Zoom - Out 


Object - action 


Immediate 


View • Zoom - Box 


Object - action 


Post-select 


Pan (World) 


Action - Object 


Immediate 


Close Window 


Action - object 


Immediate 


Resize Window 


Action ■ object 


Immediate 


Redraw Window 


Action - object 


Immediate 


Move Window 


Action - object 


Immediate 



function pointer. This process continues until an event handler 
returns a "failure" code, or a "stop the program" code. But how 
do we attach the extension structure to an Intuition object and 
retrieve it in the input handler? 

Almost all Intuition input events occur in windows, 
gadgets, menus, or menu items. Intuition's Window structure 
and Gadget structure contain generic pointer members named 
"UserData." For windows and gadgets, we can use the UserData 
member to hold a pointer to our extension structure. Unfortu- 
nately, Menu and Menultem structures don't have "UserData" 
pointers. To attach our extension pointer to menus or menu items 
without using some kind of look-up table, we have to "overload" 
Intuition's structures. We do this by defining our own menu item 
structure which has Intuition's structure as its firstmember. Here 
is the typedef for a structure we can use to overload Intuition's 
Menultem structure: 

typedef struct _myMenuItem 



struct Menultem mi; 
intuiExtens_t extens; 
myMenuItem_t ; 



Intuition's Menultem 
* our extension 



Table Two 

BREAKDOWN of Demonstration CAD Program Commands 

Command Interface Object Event 


Event Handler 


Quit 


Menultem 


MENUPICK 


miQuit( ) 


Select 


Select button 


MOUSEBUTTONS 


windowEvent{ ) 


Drag 


Mouse 


MOUSEMOVE 


multiple 


Move 


Menultem 


MENUPICK 


miSetAction( ) 


Size 


Menultem 


MENUPICK 


miSetAction( ) 


Rotate 


Menultem 


MENUPICK 


miSetAction( ) 


View all 


Menultem 


MENUPICK 


miFullView( ) 


Zoom in 


Menultem 


MENUPICK 


miZoom( ) 


Zoom out 
Zoom Box 


Menultem 


MENUPICK 


miZoom{ ) 


Menultem 


MENUPICK 


miSetActionf ) 


Pan 
Close 


Prop Gadget 


GADGETUP 


panViewf ) 


System Gadget 


CLOSEWINDOW 


windowEvent{ ) 


Resize 
Redraw 


System Gadget 


NEWSIZE 


windowEvent( ) 


Intuition 


REFRESHW1NDOW 


windowEvent( ) 


Move Window 


System Gadget 


automatic 





Since Intuition's Menultem structure is the first member 
of myMenuItem_t structures, myMenuItemJ: structures can be 
safely cast to Menultem structures. If (and only if !) all of our menu 
items are created as myMenuItemt structures, Menultem struc- 
tures can also be safely cast to myMenuItem_t structures. 

To retrieve our extension structure pointer inside an 
input handler, we examine the event message to determine what 
input object the message applies to. If it applies to a menu item, 
we get the address of the menu item, cast it to "myMenuItem_r*", 
and then get the pointer to our extension. If it applies to a gadget, 
we get the pointer to the gadget by casting the "IAddress" 
member of the IntuiMessage structure to "Gadget *", then get the 
pointer to our extension by casting the gadget UserData member 

to "IntuiExtension_t*". The ex- 
tension pointer is retrieved from 
a window pointer in the same 
way. You can look at the proce- 
dure handlelnput( ) in the dem- 
onstration program to see how 
these pointers are cast, retrieved, 
and used. You can also see how 
simple the code for the input 
handler is. 

Commands and Events 

Event-driven programs re- 
ceive commands through 
events, so the commands a pro- 
gram recognizes have to be 
mapped to events and to inter- 
face objects which generate 
events. Simple commands can 
be mapped to a single interface 
object, and received as a single 
event. Complex commands 
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usually need to be broken up, the pieces mapped to 
two or more interface objects, and then received as 
multiple events. Inside the program, the events 
have to be interpreted as commands, or pieced 
together into a complete command. Event handlers 
are the program procedures which interpret and 
implement commands by performing an action, or 
by piecing commands together from information 
in a program's state vector. 

Let's look at the commands in our demon- 
stration program to see how they are implemented 
through events. The commands, their syntax, and 
their modes are shown in Table One 



Typedefs for 'action' and 


'mldata' 






typedef int 


(*actionProc_ 


_t) (struct 


Window*, long, void* 


); 


typedef struct _miData 








acticnProc_ 


_t action; 


/* action 


procedure pointer 


*/ 


long 


modifier; 


/* action 


/object modifier 


*/ 


void 


*data; /* 


action procedure data */ 




) miData_t ; 











Which Intuition interface objects do we map our com- 
mands to? The "Close," "Resize," and "Drag" system gadgets a re 
clear choices for the "Close Window," "Resize Window/' and 
"Move Window" commands. The mouse select button is used to 
select objects, and the mouse cursor is used for dragging objects. 
Gadgets, menu items, and menu subitems are good interface 
objects to use for specifying objects, actions, or modifiers. I prefer 
using gadgets for simple, immediate commands, and menu items 
and subitems for complex commands. The demonstration 
program's commands and their corresponding interface objects, 
events, and event handlers are shown in Table Two. 

Let's take a look at what each handler in the demonstration 
program does, and where each gets the data it needs: 

WindowEvent( ) processes all MOUSEBUTTONS, NEWSIZE, 
REFRESHW1NDOW, and CLOSEWINDOW events. For 

MOUSEBUTTONS events, windowEvent( ) converts window 
coordinates to world coordinates and calculates the world coor- 
dinate distance corresponding to three pixels in x or y, whichever 
is largest. These values are saved in the state vector. The state 
vector is examined to see if an object has already been selected. If 
not, windowEventf ) calls findObject( ) to search for an object 
located within three pixels of the mouse "pick" point. If an object 
is found, its pointer is placed in the state vector. Finally, if an 
"action" procedure pointer is in the state vector, windowEvent( 
) calls the procedure. When CLOSEWINDOW events are re- 
ceived, windowEventf ) just returns a non-zero value to 
handlelnput( ), which causes it to stop processing input and 
return to main( ). This is one of the ways the demonstration 
program is stopped. For REFRESHWINDOW events, 
windowEventf ) calls drawAllf ) to redraw the model world. If a 
NEWSIZE event is received, windowEventf ) ca!lssetPanGadgets( 
) to adjust the size of the pan gadgets. Note that resizing a "smart 
refresh" window will generate a NEWSIZE event, but won't 
generate a REFRESH WINDOW event unless the window is made 
larger. WindowEvent( ) gets all of the data it needs from the 
program's state vector, the window pointer, and the IntuiMessage 
event structure. 

The demonstration program has only two gadgets. One 
is a horizontal "scrollbar" used to pan the world view left or right. 
The other is a vertical scrollbar used to pan the view up or down. 
The event handler for both gadgets is pan View( ), which is called 



when a GADGETUP event is generated, When panView( ) is 
called, it updates the window's view transform and redisplays 
the model world. The data needed in panView( ) is obtained from 
the program's state vector, the IntuiMessage event structure, and 
the gadget pointer. 

MENUPICK events are handled by several different 
event handlers. Which one is called depends on which menu item 
is selected. As mentioned above, menus and menu items are good 
interface objects for setting up complex commands. Combina- 
tions of actions, objects, and modifiers can be attached to menu 
items, and then sent to event handlers when the menu items are 
selected. To send all of this information to a menu item event 
handler, we define an "miData" structure to store all the data in 
one place. The typedefs for the "action" procedure and the 
"miData" structure are shown above. 

A pointer to the miDataJ structure for a menu item is 
placed in the intuiExtension_t structure attached to the menu 
item. This becomes the "data" pointer which is sent to a menu 
item event handler when it is called from the event input proce- 
dure. The menu item event handlers in the demonstration pro- 
gram are miQuit( ), miFullViewf ), miZoomf ), and miSetAction( 
)■ 

MiQuitf ) iscalled when the "quit" menu item is picked. 
MiQuitf ) returns a non-zero value to handlelnputf ), causing it to 
stop processing input and end the program. MiQuit( ) doesn't 
require any data at all to do its job. 

The "View-all" menu item command means "show me 
a full view of the world". This is an immediate mode command 
and it is implemented in miFullViewf ). MiFullView( ) calls 
fullDisplay( ) to find the extent of the world coordinates, calculate 
a new view transform which will fit the entire model world 
centered in the Intuition window, and redisplay the world data. 
The only data miFullViewf ) needs is a pointer to the state vector 
and a pointer to the Intuition window. 

The menu item handler for both the "Zoom-in" and 
"Zoom-out" menu items is miZoomf ). "Zoom-in" and "Zoom- 
out" are good examples of commands with action modifiers. The 
action part of thecommands is "Zoom" and the modifiers are "in" 
and "out." Zooming is accomplished by rescaling the window's 
view transform, then redisplaying the model world. In the dem- 
onstration program, when the zoom-in menu item is picked, the 
view scale factor is multiplied by two. This causes the model 
world to be redisplayed at twice its previous size. Likewise, to 
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zoom out, the view scale factor is multiplied by one-half, which 
causes the model world to be redisplayed at half its previous size. 
Since miZoom( ) is called for both the "zoom-in" and "zoom-out" 
menu items, a ZOOMIN or ZOOMOUT modifier is placed in the 
miData_t modifier field so that miZoom( ) can determine which 
way to zoom the view. The only other data miZoomf ) needs is an 
intuition window pointer, which it gets from the IntuiMessage 
structure. 

MiSetAction( ) is called when the "move," "size," "ro- 
tate," or "zoom-box" menu items are picked. MiSetAction( ) 
places a function pointer to the action procedure which will 
process the action part of the command in the program's state 
vector. It also places modifiers and pointers to the data the^ction 
procedure will need into the state vector. Basically, miSef^tion( 
) is placing part of a command into the state vector for later use. 
When an object is selected (in windowEvent( )), the command 
will be complete and the action procedure will be called. The data 
which miSetActionf ) needs is an action procedure function 
pointer, an action or object modifier, and any other data the action 
procedure will require to do its work.^his information is ob- 
tained from the miData_t structure pointer sent to the menu item 
event handler. The action procedures sent to miSetActionf ) are 
dragAndMove( ), dragAndSize( ), dragAndRotate( ), and 
dragZoomBox< ). The corresponding MiData_t structures are 
moveData, sizeData, rotateData, and zoomBoxData. You can 
look at the program code to see how these structures are defined, 
initialized, placed in^fe myMenu_t structure for each menu item, 
and then placed in the state vector by miSetAction( ). 

As you can see, attaching event handlers and data to 
Intuition input objects simplifies event processing and makes the 
logic in our event handlers pretty simple! We've seen how the the 
event handlers communicate information to each other using the 
program's state vector and decide what to do from information in 
the state vector. Now let's see what the state vector looks like, and 
see which procedures set and use its members. In the demonstra- 
tion program, the state vector is called "world,^fcnd it is a global 
instance of the following structure: 

_world 



typedef struct 
{ 

doable minx,miny; 

double maxx.maxy; 

actionProc_t action; 

object_t *selected; 

void *data; 

long modifier; 

long pickX,pickY; 

double wrldX, wrldY; 

double eps; 

object_t 'objects; 

trans fom2_t *viewTf; 

double aspect; 
} world_t; 



/* world extent lower left */t 

/* world extent upper right */ 

/* action procedure pointer */ 

/* selected object */ 

/* action procedure data */ 

/" action-object modifier */ 

/* select pick coordinates */ 

/* world coordinate pick pt V 

/* world search distance */ 

/* list of world objects */ 

/* current view transform */ 

/* window aspect ratio */ 



The "action," "data," and "modifier" membersare set in 
miSetAction( ) when an "Action" menu item or the "Zoom- box" 
menu item is picked. The action member is used in windowEvent( 



) to determine if the action part of a command has been specified, 
and if so, to call the action procedure. The data and modifier 
members are general-purpose members used either by menu 
item event handlers or by "action" procedures. 

The "selected," "pickX," "pickY," "wrldX," "wrldY," 
and "eps. "members are set in windowEvent( ) and are used in 
findObject( ) and the "drag" action procedures. "Selected "points 
to whatever model object is within a distance of "eps" of the 
mouse pick coordinates, "pickX" and "pickY."The pick distance, 
"eps," is calculated each time windowEvent( ) is called. Since the 
world distance corresponding to our pixel pick distance (3 pixels) 
will change when the view transform changes, "eps" needs to be 
recalculated each time we search for an object. "WrldX" and 
"wrldY" are the world coordinates which correspond to the 
mouse pick coordinates. These are calculated by transforming the 
pick pixel coordinates. 

The "objects" and "viewTf" members are used by any 
procedure which needs to access the linked list of world objects 
or to transform coordinates. The world coordinate extent mem- 
bers ("minx," "miny," "maxx," "maxy") and the view transform 
member ("viewTf") are set in fullDisplay( ) when it is called by 
miFullViewf ). The extent members are also updated whenever 
objects arc moved, resized, or rotated. The extent of the world is 
alwavs the smallest rectangle which completely contains all the 
world objects. As objects in the model world are moved, rotated, 
or resized, the size of the world changes. This method of dynami- 
cally sizing our "drawing area" is different from the method used 
in many CAD systems. Usually, the size of the drawing area for 
a model world must be set up in advance, and can not be easily 
changed later on. Dynamically sizing the world removes artificial 
program limits on the size of a drawing. 

Although the demonstration program accepts only a 
few commands, the techniques it uses to interpret events as 
commands and process the events can be used in any event- 
driven program, no matter how complex. Event-driven pro- 
grams arc like "Rube Goldberg" machines; a simple little event 
sets off a whole chain of actions that state changes, which even- 
tually result in the program doing what the user wanted it to do. 
The trick in event-driveVprogramming is to build the chain by 
linking simple parts together with event handlers and a state 
vector. After you develop a "feel" for visualizing how simple 
actions can be chained together using the above techniques, 
you'll be able to easily write event-driven programs which can 
handle almost any command. 

Here are the main points to rememba about she technique: 

1 Program commands are placed in "action-object" or 
"object-action" sentence fragments. 

2. Command actions, objects, and modifiers are mapped to 
graphical interface tools which generate events. Complex 
commands are mapped to multiple interface tools. 

3. Event handler procedures which implement command 
actions or modify a program's state are attached to 
graphical interface tools, and called using function 
pointers when the tools are picked. 
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4. The state information and data for event-driven programs 
is kept in a stale vector. Event handlers communicate data 
and control information to each other using the state 
vector, and use information in the state vector to piece 
toge flier complex commands. 

Drag Interaction 

Up to this point, we have seen how the top-level control 
flow for our program is implemented with event-driven pro- 
gramming techniques. The real work in our program is done by 
the procedures which enable us to move, scale, or rotate world 
objects with the mouse, and to pan and zoom the view window. 
The action procedures used to transform world objects by drag- 
ging them with the mouse are drag AndMove( ), dragAndSize( ), 
and dragAndRotate( ). These are the procedures whose pointers 
are placed in the state vector by miSetAction( ), and called by 
windowEvent{ ) when an object is picked with the mouse select 
button. The action procedure for the "Zoom-box" menu item is 
dragAndZoomf ). All four of these procedures use "drag" inter- 
action (also called "rubber-banding") to obtain transform values. 

The basic drag technique is to continuously erase and 
redraw a copy of an object as the cursor moves. When the drag 
"end" event occurs, the overall change in the cursor's position is 
used to calculate the change in the object's position, size, or 
orientation. The object is then erased from its original position, its 
new position is calculated, and it is redrawn. To avoid erasing 
anything which is under the object as it is being dragged, all drag 
drawing is done in COMPLEMENT (exclusive-or) mode. 
Complement mode inverts bits in a screen or window's bit- 
planes: any bit that is "I" becomes "0", and vice versa. If a line is 
drawn in complement mode, then drawn again at exactly the 
same location, the original bit pattern is restored. Effectively, the 
object is erased without 



The algorithm is pretty simple, but there are a few 
details w^e need to take care of to make it work correctly. First, if 
a MENUVERIFY event is received (menu button pressed) while 
an object is being dragged, we need to set the input message 
"Code" member to MENUCANCEL before replying to the mes- 
sage. This lets Intuition know we don't want a menu to be popped 
up while an object is being dragged. Second, after the input loop 
ends, we need to make sure the object has been erased and 
redrawn at its final position before we call dragDraw to end the 
drag. Otherwise, since the object is being erased by being drawn 
in COMPLEMENT mode, the draw and erase will get out of sync 
and the object won't actually be erased. Finally, for the procedure 
to work, we have to let Intuition know the window is to receive 
MOUSEMOVE events. We do this by setting the FOLLOWMOUSE 
flag in the NewWindow structure's "Flags" member when the 
window is created. 

Let's look at the demonstration program's "dragDraw" 
procedures to see how they interact with handleDrag( ). The 
procedures are moveDrag, sizeDrag( ), rotatcDrag( ), and 
zoomDrag( ). They all perform the same steps: 

Erase the drag object by drawing it in COMPLEMENT mode. 
If the drag code is BEGINDRAG or ENDDRAG, 

return. 
Else 

Use move delta values to calculate object's new position, size, 

or rotation. 

Draw the drag object in COMPLEMENT mode. 



erasing anything under it. 
Since all drag 
procedures work the same 
way, we can write a single, 
general-purpose "drag 
handler" procedure and 
use it for any drag interac- 
tion. The drag handler in 
the demonstration pro- 
gram is handleDrag( ). It 
processes MOUSEMOVE 
input events and uses a 
function pointer to call a 
drawing procedure to 
erase, move, and redraw 
theobjectbeingdragged.lt 
is called from the four "ac- 
tion" procedures. The al- 
gorithm for handleDrag( ) 
is showTi in table three. 



Table Three 



Algorithm for handleDragC ) 



INPUT: 



OUTPUT: 



win • pointer to IDCMP window, 

object - pointer to object being dragged, 

startX.startY - starting mouse position, 

moveEps - amount by which mouse must move before dragDraw procedure is called. 

dragDraw - pointer to dragDraw procedure. 

dx.dy - Overall change in mouse position. 



Save window's foreground pen color, drawing mode, and IDCMP flags. 

Set foreground color to window background color. 

Set drawing mode to COMPLEMENT. 

Modify IDCMP so window receives only MOUSEMOVE, MOUSEBUTTONS. and MENUVERIFY events. 

Call dragDraw procedure to draw object at its initial position. 

Do until SELECTDOWN event is received. 

Calculate overall mouse move (dx.dy) values. 

Calculate current mouse move values. 

If current mouse move values in x or y are greater than or equal to move epsilon value. 
Call dragDraw procedure to erase object. 
Move object, and redraw object. 
End do. 

Call dragDraw procedure to erase object from its final position. 
Restore window's initial pen color, drawing mode, and IDCMP flags. 
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Figure One 

Move Drag Calculations 



Object Containing 
Rectangle 

(RX1 



Drag StartX, StartY 
(RX2, RY2) 



(RX3, RY3) 
Drag Rectangle 




(X2, Y2) 



(X3. Y3 



DX 
DY 
X1 
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X4 



Mouse X 
Mouse Y 
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+ DX 



StartX 
StartY 
Y1 = 



+ DX, Y2 = 
+ DX, Y3 = 
+ DX, Y4 = 



RY1 + 
RY2 + 
RY3 + 
RY4 + 



DY 
DY 
DY 

DY 



Figure Two 



Size Drag Calculations 



Object Containing 
Rectangle 



The object being dragged is not the actual world object 
which was selected. Instead, it is the smallest rectangle which 
contams the selected object. The rectangle data is set up by the 
drag action procedure which calls hand!cDrag{ ). In the case of 
zoomDrag( ), there is no selected object. Instead, a rectangle is 
being created which defines a new view window. 

MoveDrag( ) moves the rectangle by adding the change 
in coordinate values to its previous coor- 
dinate values. SizeDrag( ) interprets the 
delta coordinate values as changes in the 
width and height of the drag rectangle. 
The delta values are subtracted from, 
and added to, the rectangle's corner co- 
ordinates to change its size. ZoomDragt 
) is very similar to sizeDrag( ), except the 
rectangle is resized relative to its start- 
ing corner instead of its center. Figure 
One shows how the delta coordinate 
values are used to drag a rectangle, and 
Figure Two shows how the values are 
used to resize a rectangle. 

The code for rotateDrag( ) is 
somewhat complicated because it has to 
calculate angles and use a rotation ma- 
trix to rotate the rectangle as it is being 
dragged. RotateDrag( ) uses the delta 
coordinate values to calculate thechange 
in the rotation angle for the rectangle. 
The mouse cursor x and y coordinates 
are interpreted as the horizontal and 



vertical distances from the center of the rectangle. 
The rotation angle corresponding to these distances 
is found by calling the library function atan2( ). 
Figure 3 illustrates how a rotation angle is found 
using drag delta coordinate values. The previous 
rotation tingle is subtracted from the new rotation 
angle to find the change in the rotation angle. This 
value is then used to incrementally rotate the rect- 
angle around its center. To simplify the rotation 
code, the rectangle is created as a polygon using 
world coordinates. Incidentally, the Lattice docu- 
mentation for the angle returned by atan2( ) is incor- 
rect. The procedure returns an angle in the range -PI 
< angle <= PI, not -PI/2 < angle <= PI/2 as the 
documentation states. 
Ij. Now that we know how handleDrag{ ) and the 

"dragDraw" procedures work, let's see how the 
drag "action" procedures set up the data for the call 
to handleDrag( ), and then use the drag return val- 
ues. Again, they all perform basically the same op- 
erations. First, the selected object is highlighted by 
drawing it in a "highlight" color. Next, the coordi- 
nates of the minimum containing rectangle (MCR) 
around the object are placed into an array. The array 
of rectangle coordinates is then sent to handleDrag( ), 
along with the rest of the data handleDrag( ) needs. After 
handleDrag( ) returns, the highlighted object is erased and the 
overall change in the position of the mouse is used to find the 
"move" translation value, the "size" scale value, or the "rotate" 
rotation angle. The object is transformed, its minimum contain- 
ing rectangle values are updated, and it is redrawn by redrawing 
the entire window (this can be optimized so that only the object 
is drawn). DragZoomBox( ) is slightly different, since it is used to 
create a rectangle whose position and dimensions define a new 
view window for the view transform. 



(X4, Y4) 



(X1.Y1 



(X3, Y3) 
Drag Rectangle 




(X4, Y4) 



Containing Rectangle 
Center (CX, CY) 



DeltaX = ABSfMouse X - CX) 
DeltaY = ABS(Mouse Y - CY) 
X1 = CX + DeltaX, Y1 = CY - DeltaY 
X2 = CX + DellaX, Y2 = CY - DeltaY 
X3 = CX + DeltaX, Y3 = CY - DeltaY 
X4 = CX + DeltaX, Y4 = CY - DeltaY 
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The main differences in the "action" proce- 
dures are the way the drag rectangles are set up andhow 
the changes in the mouse position are used to calculate 
transform values. DragAndMove( ) and dragAndSize( ) 
construct the drag rectangle as an array of pixel coordi- 
nates. This is done by transforming the selected object's 
minimum containing rectangle world coordinates to 
view coordinates. DragAndRotate( ) constructs the rect- 
angle as a polygon array in world coordinates, and also 
saves the initial rotation angle in the polygon array. 
Both dragAndSizef ) and dragAndRotatef ) construct 
the drag rectangle by finding the center coordinates of 
the selected object's containing rectangle, then subtract- 
ing and adding half the rectangle's width and height to 
the center coordinates. This makes the center of the 
rectangle its drag point, which simplifies the sizingand 
ro ta tion cal culations. DragZoomBox( ) cons tructs a pixel 
coordinate rectangle whose left, top and right, bottom 
coordinates are the same. As the mouse cursor moves, 
the rectangle "grows" in the direction the mouse is 
moving. 

After handleDragf ) returns, dragAndMove( ) 
finds x and y translation values in world units. To find the 
translation values, the change in pixel coordinate values are 
added to the pixel coordinates corresponding to the world center 
coordinates. The resulting view coordinates are then transformed 
to world coordinates, which yields the directed world distances 
along the x and y axes. DragAndMove( ) sends the translation 
values to moveObject( ), which adds the values to the object's 
coordinates. 

For sizeAndDragf ) and rotateAndDrag( ), the data 
needed to find the scale and rotation transform values are ob- 
tained by comparing the rectangle's initial values with its final 
values. SizeAndDrag( ) finds x and y scale values for resizing the 
object by simply calculating the ratio between the original width 
and height of the rectangle and its width and height after the drag 
is complete. Pixel values are adequate for finding scale values. 
The object is resized in resizeObjectf ), which creates a transform 
matrix, then scales the object by transforming each of its coordi- 
nates. RotateAndDrag( ) computes the change in the object's 
rotation angle by subtracting the drag start angle from the final 
rotation angle. The change in the object's rotation angle is then 
sent to rotateObject( ). Like resizeObjectf ), rotateObject( ) creates 
a transform matrix and rotates the object by transforming each of 
its coordinates. 

After handleDrag( ) returns to dragZoomBox( ), the 
coordinates of the newly-created rectangle are used to find view 
transform values which will fit the world area contained in the 
rectangle into the Intuition window. This is done by converting 
the pixel rectangle coordinates to world coordinates, then calling 
worldWindowToViewWindow( ) to find the translation and 
scale values for the new view transform. 

Although obtaining values through "pick and drag" 
interaction involves quite a bit of detailed code, the resulting 
programs are elegant and easy to use. Further, all drag interac- 
tions use the same basic techniques as those just discussed and 
presented in the demonstration program. If you understand how 
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handleDrag( ) works, and how it interacts with its caller and with 
its "dragDraw" procedures, you should be able to easily modify 
the procedures and implement various types of drag interaction 
in your own programs. 

Selecting Objects 

Before an object can be dragged, it has to be selected. 
When a select button "pick" event occurs, how do we determine 
if an object was selected? What we have to do is find the object 
which is closest to the pick coordinates, then decide if it is "close 
enough" to the coordinates to qualify as being selected. In the 
demonstration program, "pick events" are handled in 
windowEvent( ), which calls findObject( ) to determine which 
world object is closest to the pick coordinates. If the nearest object 
is within three pixels of the pick coordinates, the object is selected. 
Before calling findObject( ), windowEvent( ) transforms the pick 
coordinates to world coordinates, and finds world coordinate 
distances along the x and y axes corresponding to three pixels. 
The larger of these distances is used as the "close enough" pick 
value. FindObject( ) iterates on the list of world objects and calls 
point2Poly( ) to actually calculate the distance from the pick 
coordinates to each object. If an object within the pick distance is 
found, findObjectf ) returns the pointer to the object. Point2Poly( 
) finds the minimum distance from a point to a polygon by 
calculating the minimum distance from the point to each of the 
line segments in the polygon. 

The demonstration program doesn't "screen" objects 
before calculating the distance from the pick point to each object. 
It just examines every object until it finds one which is within the 
pick distance of the pick point. In actual CAD programs where 
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hundreds or thousands of objects are present, a variety of tech- 
niques are used to avoid calculating distances. An effective and 
simple technique is to screen out objects whose minimum con- 
taining rectangle is farther from the pick point than the pick 
distance. This can be done using only additions, subtractions, and 
comparisons. More complex techniques minimize the number of 
objects which have to be searched by partitioning the data using 
tree structures, or by keeping the objects sorted. 

Panning with Proportional Gadgets 

We saw above how our demonstra tion progra m "zooms" 
a view with menu items and, in the case of "zoom-box," through 
drag interaction. Now let's see how "panning" a view can be 
implemented using Intuition proportional gadgets. 

Look at a Workbench window. A vertical scrollbar is 
located on the right side of the window and a horizontal scrollbar 
is located at the bottom of the window. Workbench windows also 
have up, down, left, and right arrows attached to the scrollbars. 
The solid, filled region inside the scrollbars is called a "knob" or 
a "slider. " The rectangle the slider is inside is called a "container." 
When a scrollbar's slider is moved, the data in the window 
containing the scrollbar is "panned" (moved) up, down, left, or 
right. Selecting a scrollbar's arrows also pans the window. 

If a Workbench window is resized, the scrollbar's slider 
changes size. If the window is made so small that some of the 
icons are no longer visible, the slider becomes smaller. Similarly, 
if the window is resized so that all of its icons are visible, the slider 
becomes larger and completely fills its container. Scrollbars are 
designed to provide a visual indication of the amount of data in 
a window which is visible, and also indicate where the "hidden" 
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data is located with respect to the window. The size of the slider 
reflects the percentage of the window's data which is visible. The 
size of the unfilled regions inside the slider's container represents 
the percentage of the window's data which is to the left, right, 
above, or below the window. 

Let's see how to create scrollbars for our drawing win- 
dow and hook them up to our view transform procedures. We'll 
use Intuition's proportional gadget and let Intuition take care of 
moving the slider when a user drags it, or clicks the select button 
in the slider's container. To keep life simple, we'll omit the 
scrollbar arrows. To create a proportional gadget, we need to set 
up three data structures. They are a Gadget structure, a Proplnfo 
structure, and an Image structure. The Image structure contains 
the "imagery" for the slider. We can create our own slider image, 
or let Intuition create one for us. We'll take the easy path and let 
Intuition create our slider. We still have to provide Intuition with 
an Image structure it can use for the slider, but we don't have to 
initialize it. 

The Proplnfo structure contains all the interesting infor- 
mation about proportional gadgets. This structure is used to set 
up the initial size and location of the slider. Later, when the slider 
is moved, Intuition updates the values in the Proplnfo structure 
and our program can look at the values to tell how much to pan 
our view window. If the program's Intuition window is resized 
or if the size of our model world changes, our program can also 
update the values in the structure so the slider's position and size 
reflects the new window or world size. The Proplnfo structure 
members we are interested in are the "Flags" member, the 
"HorizPot" and "VertPot" members, and the "HorizBody" and 
"VertBody" members. Intuition uses the rest of the Proplnfo 
members and we don't need to worry about 
them. 

The Flags member contains the bit values which 
let Intuition know whether we want it to auto- 
matically take care of creating and moving the 
slider, and know the direction in which the slider 
can be moved. For the vertical scrollbar, we set 
Flags to AUTOKNOB I FREEVERT. The Flags 
value for the horizontal scrollbar is set to 
AUTOKNOB I FREEHORIZ. AUTOKNOB tells 
Intuition to take care of the slider. FREEVERT 
and FREEHORIZ specif}' the direction the slider 
can be moved: FREEVERT for the vertical slider, 
and FREEHORIZ for the horizontal slider. 

The Pot variables and Body variables repre- 
sent the percentage of the data in a window which 
is hidden (Pot) and visible (Body). The Body 
variables are used by Intuition to determine the 
size of the slider and how much to move it when 
the select button is clicked in an empty part of the 
slider's container. Both the Pot and Body vari- 
ables are "unsigned short" and range in value 
from to 65537. Intuition defines macros called 
M AXPOT and M AXBODY which can be used for 
the largest Pot and Body values. To use the Pot 
and Body values, we have to interpret them as 
percentages: is interpreted as 0% (none), and 
MAXPOT and MAXBODY are interpreted as (ah 
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most) 100% (all). When Pot is 0, all of our model world is visible 
in the drawing window, and when it is MAXPOT, none of our 
model world is visible. Likewise, when Body is MAXBODY, all of 
our model world is visible and the slider fills the entire container. 
The Body value in our program can never be 0, since some of our 
model world will always be visible. The Pot value is used by 
Intuition to determine where to locate the left side of a horizontal 
slider and the top of a vertical slider. 

To see how the Pot and Body values are related to each 
other and to the data which is displayed in an Intuition window, 
suppose 50% of our model world is visible and 50% of it is hidden. 
The size of the slider will then be 50% of the size of its container, 
and 50% of the container will be empty. If 25% of the model world 
is to the left of our Intuition window, the leftmost 25% and the 
rightmost 25% of the container will beempty. Figure4shows how 
the Pot and Body values are related to the visible and hidden parts 
of our model world. 

Let's develop the formulas we'll need to set the Pot and 
Body values and to determine what the values mean when our 
program receives "pan" events. We'll only look at the horizontal 
scrollbar, since thecalcttlations are similar for the vertical scrollbar. 

To set the Body value, we need to determine the percent- 
age of the model world which is visible in the Intuition window, 
and to set the Pot value, we need to determine the percentage of 
the model world which is hidden to the left of the window. The 
first step is to find the left and right coordinates of our model 
world in view coordinates. To do this, we transform the world 
minx and maw values, using point2dForward( ). We then find 
the left and right coordinates of our view window. After we have 
these values, we can calculate the percentages. If wland wr are the 
left and right coord inates of the world (in view coordinates), and 
vl and vr are the left and right coordinates of the view window, 
then the formulas are: 

world width: wwidth - wr - wl 

data hidden on the left: lhid = KAX(vl - wl.OJ 

3ata hidden on the right: rhid - MAXfwr - vr.Oj 

total hidden data; hidden - lhid * rhid 

percent of world visible: visPsrcent = (wwidth-hidden) /wwidth 

percent of world hidden on the leftt leftPercent = MAX( lhid, 01 /hidden 

Body value = visPercent " MAXBODY 
Pot value leftPercent * HAXPCT 

Why do we use MAX to find the hidden data values? 
Because, if the view is zoomed out far enough, the left and right 
sides of the world will be inside the view window and the values 
will be negative. In this case, the hidden percentage should be 0. 
Using the MAX macro takes care of this situation. 

The above formulas are used in setPanGadgets( ) to set 
the Body and Pot values. After the Body and Pot values are found, 
NewModifyProp( ) is called to let Intuition know that the scrollbars 
are to be updated. SetPanGadgets( ) is called any time the size of 
the world or the size of the view window changes. 

When a scrollbarslider is moved, our program receives 
a GADGETUP event, and the input handler calls panView( ) to 
handle the event. To pan our view window, we need to find new 
translation values, update our view transform, and erase and 
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redraw the model world. We can find the x translation value 
which will pan the view from two values: the number of world 
coordinate units which are actually hidden to the left of the 
window, and the number of units which will be hidden after the 
view is panned. If the number of units which are to be hidden is 
subtracted from the number of units currently hidden, the result 
will be the change in the current translation value which will pan 
the view. We saw above how to find the number of hidden units 
to the left of the window. To find how many units will be hidden 
after the view is panned, we multiply the total number of hidden 
units times the percentage represented by the Pot value. The first 
step in the calculations is to transform the world extent to view 
coordinates. We then use the following formulas: 

data hidden on the left: lhid = MAX{vl - wl,D) 

data hidden on the riant: rhid = EfAXCwr - vr,0) 

total hidden data: hidden = ihid + rhid 

percent of data to hide on the left: leftPercent - Pot / HAXPOT 

world units to hide on the left: hide = leftPercent * hidden 

x translation increment: txlnc - lhid - hide 

x translation value: tx - current H translation value + txlnc 

The value calculated for txlnc is an incremental transla- 
tion value. By adding the increment to the current translation 
value, we arrive at the actual translation value for our new view 
transform. 
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There is one case where these translation formulas 
won't work: if the entire world is completely inside the view 
window. As noted above, this happens if we zoom the view way 
out. We can detect this situation by looking at the Body value: if 
it is equal to MAXBODY, the entire world is inside the view 
window. Even if this is the case, we may still be able to pan our 
view to center the world in the view window. To do this, we find 
the translation increment by subtracting the center coordinate of 
the world window from the center coordinate of the view win- 
dow. The formulas are: 

world center x: wc = (wl + wr)/2 

view center x: vc = (vl + vr)/2 

x translation increment: txlnc = vc - wc 

x translation value: tx = current x translation value + txlnc 

After we have our translation values, we erase every- 
thing, update the view transform, and then redisplay the model 
world. Before calling it quits, there is one more detail we need to 
take care of: panning may bring the entire model world into view. 
This happens when the view is first zoomed out and then panned. 
When this occurs, we need to call NewModifyProp( ) to reset Pot 
to and Body to MAXBODY. 

Now, for the easy part. When we create our scrollbars, 
we use relative positioning and relative sizing for them. This is 
done by using negative values for the scrollbar location and 
width (or height), and by setting the "GREL" flags in the gadget 
structure's Flags member. For our horizontal scrollbar, we use 
GRELWIDTH and GRELBOTTOM to specify that the width of 
the scrollbar is relative to the width of the window, and its 
location is relative to the bottom of the window. GRELHEIGHT 
and GRELRIGHT are used for the vertical scrollbar. By using 
relative positioning and sizing, we let Intuition do all the work of 
keeping the scrollbars the right size and in the right place. 

Finally, to connect our pan event handler code, panView( 
), to the scrollbar gadgets, we create an in tuiExtension_t structure 
containing a pointer to panView( ). We then place the structure 
pointer in the UserData member of the scrollbar gadget struc- 
tures, and set the RELVERIFY bit in the IDCMPFIags member. 
RELVERIFY tells Intuition to send us a GADGETUP event when 
the scrollbar is selected. When handlelnput( ) receives a 
GADGETUP event, it retrieves the pointer to our event handler 
and calls it. 

Creating and Running the Demonstration Program 

To build an executable copy of the demonstration pro- 
gram, you will need to compile and link the demonstration 
program with the transform procedures. The source code tor the 
demonstration program is in the file named panzoom.c, and the 
transform procedures are in the source file named transforms. 
The Lattice (SAS) command to compile and link the program is 

lc -Lm panzoom.c transform. c 



The executable program can also be compiled and linked using 
the "make" file named panzoom.make. The command is 

Irak -f panzoom.make 

Either command will produce an executable program called 
"panzoom." 

The program displays two polygons (a triangle and a 
rectangle) centered in an Intuition window. You can move, resize, 
or rotate the polygons by selecting an action from the "Action" 
menu, picking the polygon, then dragging it with the mouse. To 
complete the action and transform the polygon, click the select 
button. If the polygons are moved or resized so that they no 
longer fit in the Intuition window, selecting the "View- All" menu 
item will calculate a new transform to fit the model world in the 
window and redisplay the polygons. The view can be zoomed in 
or out by a factor of 2 by picking either "View-Zoom-In" or 
"View-Zoom-Out". You can also zoom in on a region by first 
picking the "View-Zoom-Box" menu item, then drawing a zoom 
rectangle in the Intuition window. The zoom box is drawn by first 
selecting a corner of the zoom box, then d ragging the mouse to the 
opposite corner. The rectangle corners are selected by clicking the 
select button while the cursor is over the desired location. The 
model world can be panned by picking the scrollbars in the 
bottom or the right side of the window. The program is ended by 
picking the window's "close" gadget or by selecting the "project- 
quit" menu item. 

Summary and Preview 

In this article, we've looked at event-driven program- 
ming techniques and "drag" interaction. We've seen how these 
techniques can be combined with coordinate transforms in vec- 
tor-based CAD programs to modify graphical objects and pan 
and zoom drawings. We've now developed most of the basic 
building blocks of a vector-based CAD program: transforms and 
general-purpose input and drag handlers. The building blocks 
that are missing are geometric objects we can use to model world 
objects: lines, circles, rectangles, etc. Next time, we'll conclude 
this series by using object-oriented programming techniques 
(honest!) to create and manage geometric objects. Until then, if 
you want to experiment with the techniques presented in this 
article, add an "Insert-rectangle" menu item and code to create 
rectangles. Hint: look at how "zoom-box" works. You can also 
add a grid to the program to experiment with transforms. 
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Listing One 



panzoom.c 



panzoom.c - program to demonstrate 'rest 

world & view transform procedures, 

pan and zoom, and event-driven programing 

techniques. 



* copyright {cj 1991 by Forest w. Arnold 
V 

"include <stdio.h> 
nir.clude <exec/types.h> 
W include < intuit ion 'intuit ion. h> 
# include <graphics/gfxbase.h:> 
f include <graphics/regior.s.h> 
# include <graphics/clip.r,> 
Sinciude <graphics/layers.b> 
^include "transform. h" 

/' intuition stuff 

^define INTUIT 10N_RSV 34 

ttdefine GRAPHICS_RE7 U 

extern struct IntuitionBase "IntuitionBase; 

extern struct GfxBase 'GfxBase? 

struct LayersBase "LayersEaser 



/* 



event handler procedure and data typedef s 



typedef int Cevent?roc_t) I struct IntuiMessage '.void * h 
typedef int I •actionProc_t M struct Window *, long, void ' ); 



typedef struct _intui£xtension 
{ 

eventPrtxM: handler; 

void *datar 

lntui©aension_t! 

typedef struct _rriit>ata 



actionProc t 


action; 


long 


modifier 


void 


■data; 


| iriCi=^_t; 





Intuition extension 



/* event handler 
/• data to be sent 



menu item data 

menu item action proc 
action modifier 
any data to be sent 



/' extended menu item 

/" intuition menu Item 



{ 

struct Menultem ni; 
intuiExtension^t extens; /* menu item extension 
J myMenuItem_t; 

/* define an object type 



typedef struct _object 

; 

struct _gbject 'next; 
double ninx.minyj 
double iTiaxx.maxy; 
double *poly; 
int npts; 

J object_t; 



list link field 
lower, left corner 
upper, right corner 
object '5 shape 
# of points for shape 



set up some polygons to display. The coordinates are 
stored in the arrays as xO,yO,xl,yl . , .xn,yn. 



double triangleH = 

( 400.0,-400,0, 200.0,0.0, 0.0,-400.0,400.0,-400,0 ); 

double squared = 

t -500.0,100,0, -500.0,500.0, -100,0,500.0, 

-100.0. 100.0, -500.0,100.0 
J; 

object_t obj2 = 

[ NULL, 0.0,-400.0, 400,0, 0.0, triangle, 8 f; 

object_t objl = 

I iobj2,-S00.0, 100,0,-100.0, 500.0, square, 10 ); 



define ar.d initialiie a structure to hold the 
program state and the world data. 



world lower left coords 
world upper right coords 
current action procedure 
active object 
arg tor action procedure 
arg for action procedure 
pixel pick coordinates 



typedef stmct 


jworld 


i 

double 


minx.iainy; .' * 


.; .;; .- 


naxXrOaxyi 


acticr.Froc_T 


action; /■ 


object_t 


•selected; /* 


void 


*dsta ; < ' 




ir.^difier; f* 


. .:." 


p'..rkXrP-<- !•■■-;/ 



wrldX%wrIdY;/' world pick coordinates 



double eps; 
object_t 'objects; 
trans forifi2_t *viewTf; 
double aspect; 
} world_tr 



search epsilon value 
list of world shapes 
windows view transform 
window aspect ratio 



worldjt world - 

t -550.0, -550.0, 550,0. 550,0, NULL. NULL, WULL, 
0r0,C,0,0,0.0,0,0,4Objl, HULL. 1.0 
}; 

f* Event handler procedures 

int windowEvenr. ( struct IntuiKessage # ,void * )j 
int miQuitl struct IntuiMessage *,void • ) ,- 
int miSetActionf struct IntuiMessage •,void * ); 
int miFullView( struct IntuiMessage *,void * I; 
int miZooml struct IntuiHessage *,void * ); 
int dragAndSize! struct Window *, long, void * I; 
int dragAndRotatet struct Window *, long, void • |; 
int dragAndMovet struct Window •, long, void * ); 
int dragZccm5ox( struct Window *, long, void ■ ); 

/* Menu text definitions 

struct IntuiText pro jTxt [ ] = /* project text 
I 

( 2,1,JAM2,2,1,NULL,-Qtut", NULL ), 
J) 
struct IntuiText actionTxtU = f* action text: 

I 2,l,JAM2,2,l,NULL,-Move', NULL I, 
1 2,l,JAH2,2,l,KULL,'Size-, NULL |, 
j 2,l,JAM2,2,l,NULL,'RoCate",NULL I, 



I 



struct IntuiText viewTxt(] - f* view text 



1 2,1,JAM2,2,1, NULL, 'All*, HULL ), 
{ 2,l r JAH2,2,l,NULL,'Zoom -:>",!." 



struct IntuiText zoaTTxt[] 



f* zoom text 



{ 2,1,JAM2,2,1,NULL, 'In*. NULL J, 
{ 2,1,JAK2,2.1, NULL, "Out*, NULL ), 
{ 2.1,JAM2,2,l,NULL,"Box-,NULL ), 



menu modifiers (stored with subitem) 



^define ZOCHH1 1 

•define ZOCKOUT 2 



menu item extension structure data 



;tiDaca_t moveData s 


{ dragAndHove, 


0, 


NULL ); 


niData_t sizeData = 


{ dragAndSize, 


0, 


NULL 1; 


miData_t rotateData - 


i dragAndRotate, 


0, 


NULL 1; 


miData_t zoonlnDaCa - 


( NULL, 


ZOOMIN, 


NULL (; 


B4Data_t zccr&itData - 


( NULL, 


ZOOKOUT, 


NULL I; 


miData_t zcomBoxIlata - 


( dragZociRBojt, 


0, 


NULL t; 



f* menu subicem definitions 

iryMer.uIcem_c soomTcml] = 
( 

i /* "Zoom In' sub-item */ 

{ &(zacnltm[l] .mi) ,0,0,0,0, 

ITEKTEXT I ITEMEKABLED I HIGHCOMP , , 
(AFTRJ&zoonrTxtlC] ,NULL,NULL,NULL,MENUt;ULL ). 

{ miZooni, (void*)&zoomInData ) 



I* "Zoom Out' sub-item ■/ 

( t(zoomItm[3] .mi 1 , 0,0,0, Q, 

ITEMTEX7JITEMENABLEDIHIGKCOHP.0, 

(APTRISzooiilTntll), NULL, NULL, HULL, HENUNULL ), 
( mizopm, |void*)&zoomOutData } 

t* "Zoom Sox" sub-item */ 

! NULL, 0,0,0,0, 

ITEKTEX? I ITS1ENAELED I HIGHCOMP, . 

(APTRISzoo.llT>:ti2] .HULL, NULL, NULL, HENUNULL ), 
i miSetAction, (void")tzoomBoxData J 



/* menu item definitions 

iEyMenuIteai_t pro1Itin[] = 
( 

{ /* "Quit" menuitem * 

( NULL, 0, 0.0.0, 

ITEHtEXT I ITEHENABLED I HIGHCOMP . , 
lAPTEiSprojTxtlOI.irjLL.irJLL.KULL.MENUNULL ), 

( miOuit,KULL ) 



1, 



); 

.tr/MenuItepi_t actionltml] = 



( 



"Move" nenuitem 
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i feUctionItmUJ.uii)»G,0,Q,0, 

ITEMTEXT I ITEMENABLED I HEGHCGMP, , 

(APTR1 SactionTxt [01 , NULL, KULL, HULL, MENUHULL } , 
( miSetAction, (void* ItraoveData ) 

f* "Size" menuitem */ 

( &(actionItml2I*mi) .0,0,0,0, 

I TEHTEXT 1 tTEMENABLED ! H EGHCOMP, D , 

IAPTR) &actionTxt [1] , NULL, null, null, memunull > , 
•; ir.i^etAetion. (void" )k~,i ;:er.at j ' 

/* 'Rotate* menuitem */ 
{ NULL, 0,0,0,0, 

ITEKTEXT ITEIffiKABLEDIHIGHCOKP f a, 

|APIR]SaCtionT)tC[2] ,NU1 ,N : [ , I.'JLL.MENUKULL }, 
( miSetAction, (void* l&ratateDates ) 



TyMenuIcera_t viewItmU a 
t 

{ f* "Ail* menuitem */ 
{ £{viewltm[l] .mil, 0.0,0, j, 

ITEMTEXT J ITEMENAELED I HIGKCOMP , , 
!APTR)&vie^xt[03,M^L,f4ULL,NULL,M^WUNULL }, 
{ raiFullView.NOLL ] 

( /" "Zoom" menuitem */ 

( NULL, 0,0. 0,0, 

ITEMTEXT I ITEMENABLED I HEGHCOMP, , 
[APTRS&viewTxt [1] , NULL, NULL, 

(Struct Menuitem MtzooraltmEO] .MEMtWULL] , 
{ NULL,h*ULL J 
), 



/* These are the Menu definitions 

struct Menu rrenu[] = 
{ 

( {* "Project" menu 

tmenu [ 1 1 , , , , , MENUENA3LED , 
-Project", (struct MenuItemMtprojItinCQI 
J, 

{ f* "Action" menu *i 

4menu [2],0,0,0,0, HENUEHABLED, 
"Action", (struct MeriuItem'lfcactionTtmlQ] 

h 

{ /* "View " menu 

NULL ,0,0,0,0, MENUEKABLED , 

"View ", [struct Menuitem" )&viewitm[0] 



/* scrollbar (pan) gadget definitions 

tfdefine PANHORIZ 1 
((define PANVERT 2 

/* pan event har.dier and extension data 

inL panViewl struct intulKessage *rr.sg,void * }; 

intui Extensions panExt = ( panView.NULL ); 

struct Image hlmage; /'" reserve space for intuition *■/ 

struct Image vlmage; /' reserve space Ear intuition */ 

struct Proplnfo hlnfo - 

( &UH0KHCBIFREEHORIZ, 0,0,-1,-1, }; 

struct Proplnfc vlnfo = 

f ftuTOKHOBIFREEVERT, 0,0,-1,-1, }; 

struct Gadget hPan - 

NULL ,1,-8,-15,9, GACGHCQMP I GRELWJ DTH I GRELBOTTOM, 

RELVEF.IFYISOTTOMEORDER, PROFGADGET, (APTR) ihImage,NULL, 
NULL.0, (APTR) fchlnfo, PANHORIZ, (APTR)ipanExt 

); 

struct Gadget v?an = 

( 

ihPan,-15,10,16,-18,GADGHCOMPlGHELHEIGHTIGRELRIGHT, 
RELVERIFYIRIGHTBOHDER, PRDPGADGET, (APTR! &vImage,NULL, 
NULL.0, [APTR]&vInfo,PAlTVERT ( (APTRJfcpanSxt 

); 

/* per. number definitions and drag code definitions »/ 

^define BGPEN 

^define dkaWPEN 1 

fldefine HLPEN 3 

edefine AXI5PEM 7 

sdefine BEGlIIDRAG 1 
Idefine ENDDRAG 2 

tdef ine HDi(x,y) I Ux) < (yl) ? (x) : (y) ) 

Bdefine MAKtx.y) ! (Ixl > (y) ) ? (x) i iY) > 
f* forward procedure declarations 



void handlelnput( struct Window * I; 

void handleDragt struct Window *,void *, long, long, long, 

void (*)(),loiig *,long " )r 
void sizeAndLocateMenus I struct Ker.u * r short, short); 
void sizeAndLocateWemiltemsl struct Menuitem *, short, 

short , short , short , short ) ; 
int maxMiTextLength{ struct Menuitem * ); 
struct Window "displayWindowfint , int, int, int, 

char *, struct Gadget * !; 
void closeLibst void )r 
int openLibsf void ); 
void fullPispiayi struct Window • J; 
void zoomView) struct Window *, double ) ; 
void setPanGadgets( struct Window * f; 
object_t *£indObject( object_t *, double, double, double ); 
double points Poly! object_t *, double, double ); 
void drawAlll struct Window * J; 
void drawAxis< struct window * ): 

void rirawObjeci (struct Window ",trans£orm2_t *,object_t *) ; 
void eraseAlK struct Window * ); 
void moveGbjectf object_t *, double, double }; 
void resizeObject i objeCt_t *, double, double) ; 
void rotateObject ( objeot_t *, double!," 
void moveDrag (struct Window *,void *, long, long, 

long, long, long) ; 
void sizeDrag( struct Window *,void *, long, long, 

long, long, long) ; 
void rotateDrag [struct Window " ( void •, long, long, 

long, long, long) ; 
void zQonSrag(struct Window *,void ", long, long, 

long, long, long) ; 
void drawRecU struct P.astPort ', long, long, long, long) ; 
void setWorldExtent !world_t *) j 
void getViewExtent (struct Window *, 

long ", long *,long * , long *J; 
struct Region "setClipRectf struct Window *, 

long, long, long, long) ,* 
void reinoveClifjRect (struct Window *, struct Region *!? 

void main ( int argcchar"* argv ) 
i 

intuiExtension_t windowExt = 

{ windowE'^ent, (vo:d*(iworld I; 

struct Screen screen; 

struct Window *window = HULL? 

trfflnsforai2„t tForm; 

long dpmX , dpmY ,- 

short txtHeight , txtMidth ; 



(* open, libraries & get screen info 
if [ ! openLibsl) ) 



printf (*\nCan't open system libraries. .. \n') ; 
exit (II; 

GstScreenData ( (char*) &screen,sizeof (struct Screen) , 
WBENCHSCREEN.NULL) ; 

t* calculate x to y aspect ratio 6 text dimensions V 

dptnX = (long}G£xBase->NormaIDPKXr 
dpmY ^ (long)GfxBase->NormaIDPMYr 
if ( screen, Height == 200 | 

dpmY /= 2; 
world. aspect - (double)dpmX/ ( double) dpmV ; 

txtHeight = screen. RastFort.Font->t£_¥Size; 
txtWidth s screen. RastPort.Font-^tf_KSize; 

/* set up menu positions and sizes */ 

sizeAndLocateMenusI tmenutDl , txtHeight .txtWidth ) ; 

f* open the window and attach menu */ 

window = displayWindow(50, 5D, 300,150, *Transfonr.s" , tvPan) ; 

if ( I window ) 

I 

printf ("Can't open window\n")i 

goto clean; 
) 
SetMenuStrip (window, anenu [0] ) ; 

/' set up transform & draw the world 

world. viewTf - fctForm; 

window ->UserDat a - {UBYTE* l&winccwEKt; 

£ullDispiay[ window Ji 

/* handle input until window closed */ 

handielnput ( window ) j 
clean: 

if ( window ) 
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ClearMenuStripl window ) ; 
CloseWindcwI window jj 



claseLibs () ; 
exit (0) ; 



• positions and sues 
■ I ... :.:.., 11 gnu Strip* 



void eizeAndLocateMenusi stmnr ::■;.; '■-,... 

short tHt, short tWd i 
I 

SHORT starl 2; 

. ■ ;. . 
i 

menu ~>Le ft Edge - start; 

menu- >wi 1th - tWd ■ 6trlen(nenu.->M£nul!Ja!He) * tWij 

if ( menu->Firstitem J 

sizeAndLacateMenuTtemst raenu-i-Firstltem, 

me:iu->Width, Q,0,tHt ,tWd 

.'■ at ■ ru Mi 1th i . : 



sizetadLoxMteJteiuIteais { 1 - Calculate positions and 
sizes for all men - j items and subitens in a nenu 



void sizeAndLocateNenuItemsl struct MenulLem *mi ( 

short minw, short 1, short t, 
short tHt, short 



{ 



int tKtlen; 

txtlen - roaxKiTextLength ( mi 

-■ . . 
f 

mi->TopEdge = t; 

mi->Le£tEdge = 1 : 

mi->Width - tWd * txtlen * 4f 

: : i n-.i - ; : .:.. 

mi->Heiflht - tHt • 2; 

>SubIteo ) 

' •;:iLacate>ienuItemfl< mi->SubTten.Q,nri->Wldth-8, 
■ .tWd)r 
:->Height; 
mi a mi->NextItemj 



rind longest rr.enu item text 



int maxMiTextLengthl struct Menultan # ni ! 
I 

struct IntuiT&xt 'itext; 

int len, retlen; 

retlen = Oj 

while! mi ) 
I 

Struct IntuiTaxt •)mi->ii* 
len ■ strien(itext->I7ext) : 
retlen ■ len > retlen ? len : retlen; 
; L->KextIteta; 
} 
return retlen; 



* [ftiQuitO " Menu item pick event handler. Returns 

* non-zero value to stop input pror;- . 

int niQuit< struct _:...: 



■" 



non-zerc ■■:-': L end -r; it ",_■.:. 



Henu item piclc event, handler, 
world state info for ch ■ - ion. 



int miSetActioni struct tntuiHessage *msg,voId -data \ 
I 

ntiData_t 'itmOata = r : D3ta_t")data; 

if ( itnData ) 



world. action - itmData-^action; 

world. modifier s itmData->mcdifier; 

world. data = itmDaLa->data.; 
} 

else 
( 

world. actio;. 

■: - 0; 

world. data - HULL; 



nriFullViewi) - Menu item pick event handler. 

Redisplays full riddel world centered in window. 



EntuIHessags "irsg.'.'oid "data ) 
1 

: r,$g->IDCKPWindaw»; 

return .; 

1 

* miZocunO - Menu tten pick event handler. Zooms the 
view window in or out by a factor of 2. 



int niZocT.! struct InvjiMessage *msg,void "data ) 
{ 

niData_t *itnData - <rc.iDa.ts_"' Hat ■: 

nData-smodifier == ZOOHIK ) 
2oomView(tisg->lDCWI , Wind0w,2.Q) ; 

else 

soomView(nag->IDCMPWindow,0,5) ; 

return 0; 



* vindowEvent | ) - window event handler. Called when 

an event occurs inside the input window to take 
1 care : ; w-speci£ic events, such as "close", 

* "button press" , etc. 

int vindowEvent (struct intuiHessage v. ■ ■ ■ lata ) 
I 

struct Window "window s msg->TDCMPWindow; 

double xz,yz,x,y; 

if | rsg->Class --- CLOSF^UTOOW ) 

return 1; 
else 

REFRESHMDEOW ) 
drawAll (window) ; 
else 
.: ...s_->Class =- NEWSIZE ) 

set PanGadget si window) ; /* update pan gadgets V 

else 

sB->Class == tfousEBUircNS &S. 
msg-xCode »■ SELECHJOHH I 



' 



Calculate the search epsilon value 

:n world units corresponding to three pixels 

and find the world coordinate pick values. 



point2dForward [ world. viewTf , D.0,0.Q,&xz,&vz) r 
point 2dl averse f world.viewTf,xz+-3 .0*yz+3 . 0,&x,&yl ; 
x = ABSIxl; y * AB5[y)r 
world. eps b KAXjx.y) ; 

point 2dlnverse > worl d.viewTI . iiioublt-ircsg^HauseX, 
IdoubleJmsg-^MouseY.&x.iy ); 



if an object has net elready teen selected, 
see if me :s within the pick epsilon distance 
: r ick coordinates 



if i world. selected == NULL ) 

world. selected - findObjectl world. objects, 

x, yjWorld.eps J; 
world, pickX - nisg->ItouseX; 
iCkV - r>sg->MouseY; 
world. wrldX = x; 
world. wrldY = y; 

If we have an action procedure, call it 

if l world. action I 

(void) ('world. action) (window, 

world. modifier, world. data! : 

world. selected - 'IULL; 
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fullDisplayf ) - called Co recalculate the view 
transform & redisplay the entire rrsdel world 
centered in the window. 



void fullBisplayt struct Window -window <i 
{ 

double tx,ty,sx,Sy; 

long vxl, vyb,vxr,vyt; 

getViewExtent (window, tvxl , &vy t , frvxt , &vyb ) ; 

setWorldExtenci fiworld ); 

eraseAll I window ); 

worldWindowToViewKindowI world*minx,world,miny, 
wor Id * maxx , wo r Id . ma xy , 
(double) vxl* (double)vyb, 
(double)vxr, (doublejvyt, 
workLaspect.&tx.&cy.tsx.&sy ); 

(void}setViewTransform( world. viewT£ r tx, ty,sx,sy, 0.0 ); 

SetAFen (window- >RPort,DRAWPEN> ; 

drawAll ( window ! ; 

setPanGadgets (window) ; /• update pan gadgets */ 

* zQOinViewU - Modifies the view transform scale v*l 

• and redisplays the view. 



ues 



void zoomViewf struct Window "window, double scaleVal I 

1 

double tx, ty, sx, sy,ang; 

/* get previous transform values and update them 

eraseAll ( window ) j 

getTransform! world. viewTf 1 &tx,$ty,&sx,i 1 sy,&ang| ; 

sx •= scaleVal ,* sy ■= scaleVal; 

{void)secVievrransform( world, viewTf ,tx, ty, sx. sy.ang) 

SetAPen(window->RFort,DRAWPEN} ; 

drawAllf window |j 

setPanGadgets (window! ; 



■ panViewl) - Pan gadget event handler. Called when 

■ GADGETUP event generated for pan gadget. 



inc panViewl struct IntuiHessage *cisg,void "data I 



I 



Gadget "gadg = 
struct Window "window = 
struct Proplnfo "info; 
double xl,yh,xr,ytj 
double tx,ty,sx,sy,ang; 
double oldTx. oldTy; 
double hidden, lHid, tHid 
long l,h,r r t; 
long wl,wr,wt,wb: 
long wc,c; 
long dx.dy; 



struct Gadget*lmsg->IAddress; 
nsg-:>IDCMFtfindow; 

f* transformed world extent"/ 

/• transform values "/ 

/* prev transform values */ 

/* 'hidden' amountB ■/ 

/* window extent */ 

/* world pixel extent */ 

f* world, window center */ 

f* change in coordinates '/ 



gee window extent fc world extent in window 
coordinates. Get existing transform parameters. 



getViewExtent (window, £1 , it ,.£r, fib) ; 

point2dForward( wor Id. viewTf, wor Id. minx, wor Id. miny, 

Sxl.&yb); 
po-.n-2dForward( world. viewTf, world. maxx, wor Id. moxy, 

ixr.iyt) ; 
wl ■ doubleToLong {xi ) ; wr = doubleToLong (xr) j 
wt ■ doubleToLong (ytl ; wb - doubleToLong(yb) r 
getTrans form (world. viewTf, &tx,fiity.isx r isy,4ang) : 
oldTx = tx; oldTy - ty; 



pot/MAXPOT represent the percentage of the hidden 
information which is to the left of or above the 
knob. IHid is the number of world units to the 
left of the window, and tHid is the number of 
world units above the window. Subtracting these 
values from the previous left, top hidden values 
( 1-wl & t-wt ) gives the change in the number of 
world units. If nothing is hidden, we just center 
the world by moving the world center to the window 
center. 



{struct Proplnfo* )gadg->SpecialInfo; 



if ( gacV>GadgetiD == panhoriz ) 

{ 

if ( info->HOriz3ody 1= MAX30DY 1 



I 



hidden = HAXU-wl.O) » MAX(wr-r,0); 
IHid = info->HorizPot*Mdden/KAXPCT; 
tx += {double) (1-wl) - IHid; 



else 
\ 

c = (r+l)/2; wc - doubleToLong ( (xr+xl) /2.0) ; 

tx *= (double) (c-wc] ; 
} 
} 

else 
! 

if ( info->VertBody !- HAXBODY ) 
( 

hidden - HAX(L-wt,0) - KAX{wb-b, 0) ; 

tHid ^ info->VertFot* hidden/KAXPOT; 

ty += (double) (t-wt) - tHid; 
I 

else 
I 

c = <b+t)/2; wc = doubleToLong! (yb+ytJ/2.0 J ; 

ty *■= (double) (c-wc| ; 
i 



/* if nothing changed, just return 

if ( oldTx — tx 64 oldTy == ty ) 
return 0; 

f* erase world, update view transform, redisplay 

eraseAll ( window I; 

{voidlsetViewTxansfonM world. viewTf , tx,ty,sx r sy,ang] ,- 

SetAPenl window- >RFort,npAWP£N) ; 

drawAll! window ); 



/* 



if entire world is in view, reset pan gadgets 



dx = doubleToLong(tx-oldTx) ; 
if I info->HorizBody !- maxbody fc& 
1 <- wl + cbt &fr wr + dx <= r ) 
NewHodifyPrOp !&h?an, window, HULL,AUTOKTKB IFHEEHOMZ 
0,0, HAXBODY, -1,U; 

dy = doubleToLong 1 ty-oidTy ) ; 
if ( info->VertBody !- HAXBODY && 
t <- wt+dy it wbtdy <- b ) 
HewModi fyProp (fcvPan, window, HULL, AUTOKNOBI FREEVERT, 
0,0,-1, HAXBODY. L)j 
return Oi 



setPanGadgets (I - calculate pan gadget sizes and 
positions when the view window changes. 



void setPanGadgets! struct Window 'window ) 



t 



double xl,yb,xr,yt; 
long hHidden, vHidden; 
long IHid, tHid; 
long width, height; 
lang l,b,r,t; 
long wl,wb,wr,wt; 



/* transformed world extents 

/* hidden amounts 

/* hidden left, top amounts 

/' world pixel dimensions 

/* window extents 

/• world pixel extents 



unsigned short hBody,vBod>' r hPos,vPos; 



* get the window extent and the world extent in 

* window coordinates. Find the total width & 

* height of the world. 
*/ 

getViewExtent (window, fcl.fi t,tr,tb) ,- 

point2dForwardl world. vievT f .world, minx, wor Id. mi ny, 

txl.tybjj 
point 2dForward( world. viewTf .world. maxx, wor Id. maxy, 

ixr.iyt) ,- 
wl = doubleToLong |xl) ,- wr - doubleToLong (xr) ; 
wc = doubleToLong (yt ) ; wb = doubleToLong (ybj ; 

width = A3S(wr - wl] ; 
height = ABS(wb - Wt] ; 

/* 

' {width - hHidden) /width gives the percentage 

* of the world width which is visible. Multiply 
' this value times the nax knob size to set the 

* knob size. 



IHid = 1 - wl; 

hHidden - HAXtlHid.O) + HAXtwr-r,0); 

if ( htiidden > ) 

hBody - (width - hHiddenl 'KAXBQDY/width; 
else 

hBody = HAXBODY: 

tHid = t - wt? 

vKidden = HAX(tHid,0) + HAX(wb-b, 0); 

if ( vHidden > ) 

vBody ^ (height - vHidden) "HAXBODY /height; 
else 

vBody ■ HAXBODY? 
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lHid/hliidden is the percentage of the hidden 
world units to the left of the window. Multiply 
this value times the max pot size to set the 
space to the left side of the knob. 



i£ < IBid > ) 

hPos = lHId'MAXPCT/hHidden; 
else 

hPos - 0; 

if ( tHid > } 

vPos - tHid*MAXPOT/vHidden; 
else 

vPos = 0; 

KewModifyProp(thPan,window ( NULL,AUTOKNO&IFfiEEHOKU, 
(ULONGIhPos.O, (ULOJG)hBody.-l.l); 

HewModi fyProp ( ivPan, window, MULL , AUTOKWB | FREEVERT, 
0, lULONG)vpos,-U (ULOWGlvBody.il ; 



dragZoamEox ( i - process zoom box creation 



int dragZaomBox (struct Window •window, long mod, void 'data) 



I 



struct Region 'prevRegion: 

double minx, miny , maxx . maxy ; 

double xl ,yb, xr , y t ; 

double sx, sy.tx.ty; 

long rect I4j ,- 

long dx,dy,l, t.r.b; 

/* clip to the view window rectangle 

getVievExtent (window, 5. 1 , tt , 4r , 4b) ; 
prevRegion - setClipRect (window, 1, t.r, b) ,- 



set up the pixel coordinate rectangle and call the 
drag handler. 



rect[0J a recti 2] = world. pickX; 
rect[l] - rect[3] & world. pickY; 

handleDragl window, (void*)firect, world. pickX, 
world.pickY, 1, zoomDrag, kdx.&dy ) ; 



get the box dimensions and reset the transform, 
unless zoom box or scale values are too snail 



if ( ASS(dx) >= 4 ££, ABS(dy) >=■ 4 ) 
I 

xl = (dcublelMIN'lrect(0],rect[2)]; 

yb = (doublelMMIrect|l],rect[31}; 

xr a ldoublelMAX|rect[0] i recti2Jl; 

yt ^ (doublelHIN(rect|l],rect [3)3,- 

point2dInverse( world. viewTf ,xl ,yb,&minx,£miny ); 

poinL2dlnverse( world. viewTf .xr.yt.imaxx, &maxy ); 



if ( ABS(naxx-jr.inx) 
ABStnaxy-miny} 
goto done; 



5.0 



waridW'indowToViewwindow! minx, rainy, maxx, maxy. 
(double] 1, (double)b, 
(double}r, (double)t, 
world. aspect , &tx, 4 ty , 
&sx,4sy) ; 
eraseAlK window If 

(void) setVievTrans form (woe Id . viewTf r tx, ty , sx^ sy , . ) ; 
SetAPen (window->RPort , DRAWPEH) ; 
rsnoveClipRect ( window, prevRegion ]; 
drawAll ( window ) ; 
setPanGadgets (window) ; 
world. act ion - NULL; 
return 0; 
1 
done: 

removed ipRect ( window, prevRegion |; 
return 0; 
\ 



dragAndMoveO - process move interaction 



int dragAndMove (struct Window *window,long tsod.,void 'data) 
{ 



Struct Region 


•prevRegion; 


object t 


*obj = world. selected 


long 


rect[4); 


double 


xz.yz.x.y; 


long 


dx.dy, l,t, r,b; 



If no object selected, just return 



if < obj ^= MULL ) 
return Oj 



clip to the view window rectangle and highlight 
the object 



getViewExtent (window, &l,&t,sr,&b) ; 
prevRegion = setClipRect (window, l,t, r,b| ; 
SetAPen|window->RPort,HLPEK) ; 
drawoh-ject (window, world. viewTf, obj] -, 



set up the pixel coordinate rectangle and call the 
drag handler. 



point2dForwardl world. viewTf ,cbj->tninx,Qb}-Mniny,lkx.4y) ; 
rect[Q| = doubleToLong(x) ; rect|lj = doubleToLong(y) ; 
point2dForward(wx)rld,view/Tf ,cbj->maxx,Qbj->maxy,4x.4y) ; 
trecttf] = doubleToLong(x) ; rect[3] = doubleToLong(y> ; 

handleDragl window, (void')4rect. world. pickX, 
vorld,pickY,l,moveDrag,Adx,tdy ); 



erase object, find world distance corresponding 
to drag distance* and move the object* 



Set APen (window- >RPart,BGPEN) ; 
drawObject (window, world. viewTf ,obj) ; 
point2dForward I world. viewTf ,0.0,0 . 0, &xz ,4yz } ; 
point2dInversel world. viewTf. 

xi- [double) dx.yzt (double Idy.&K.iy) [ 
moveObject(obj,x,y) ; 

/* remove the clip region 4 redraw everything */ 

resnoveCl ipRect ! window, prevRegion ]; 
drawAll (window) ; 

/" find new world extent and reset pan gadgets *l 

setWorldExte.it ( Sworld ); 

setFanGadgets< window ); 

return 0; 
\ 
■-_„__. = = ==================== = . ========.=.= . ===== ±± =i=== = 

• dragAndSizel) - process size interaction 

= *» = = = = » = ,= = = = = = = = = = = = = = === = = = = = = = = = = = = = = ,: = = = = = = = = = = = = = */ 

int dragAndSizel struct Window 'window, long mod. void *data) 
( 

struct Region *prevRegion,- 

object_t *obj - world. selected; 

double sx.sy,- 

double nunl.nu.Ti2; 

double xl,yl r x2,y2; 

long rect[6] ; 

long minx, miny, maxx, maxy; 

long cx,cy,dx,dy? 

long l,t,r,b; 



' 



If no object selected, just return 



if { obj — MULL ) 
return 0; 



clip to the view window rectangle and highlight 
the object 



getViewExtent (window, &l,*t,&r,£b! : 
prevRegion - setClipRect (window, l,t,r,b) ? 
SetAPen (window->RPort, HLPEN) ; 
drawObject (window.world.viewTf ,obj ) ; 



set up the pixel coordinate rectangle and draw it, 
then call the drag handler. 



point2dForwardl world. viewTf. obj ->m.inx,abj->tniny,4xl,iyl) ; 

point 2dForward (world. viewTf, obj ->maxx,obj->maxy, 4x2, 4y2) ; 

rectjO] - minx ■ doubleToLong(xl) ; 

rect|lj = miny ■ doubleToLong(yll ; 

rect[2) ■ maxx ■ doubleToLong(x2) ; 

rect[3| ■ maxy - doubleToLong(y2) ; 

rect[ 41 = ex = (minx + maxx)/2: 

rect[51 = cy = (miny * maxy)/2; 

drawRect (window- >RPort,,minx,niny, maxx, raaxy) ; 

hdndlePragt window, (void*)&rect.cx,cy, 1, 
sizePrag.saX&dy ) ? 
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* erase object and rectangle, find new scale values 

* and resize the object. 



SetAPen [window- >RPort,BGPENi r 
drawObject (window, world. viewTf , obj) j 
dravRect iwindow->RPort,minx,ininy r maxx,!naxy) ; 

nural . ABS|rect[2J-rect[0]); 
if I numl < 1.0 1 

nuinl = 1.0; 
num2 - ABS(rect[3]-rect[l]): 
if I num2 < 1.0 1 

nuoi2 - 1.0; 
sx = numl/(x2-xl) ; sy = -num2/(y2-yl) ; 
resizeobject (obj , sx,sy) r 



/* 



remove the clip region & redraw everything 



.- . LipRectl window, prevR-^i", , 
drawAll (window > ,- 



find new world extent and reset pan gadgets 



setWorldEXtent I fcworld !; 
setPanCadgetsI window 1; 
return 0; 



dragAndRotated - process rotate interaction 



fcnt dragAndRotatet struct Window -window, 
long mod, void 'data ) 



struct Region "prevRegion; 
object_t *obj = world. selected; 



.... ..;. _■".' 

i: .;: !•: 
long 
long 
long 




rectxy[12] .startAng; 

X L , yl, >:2 , y2 , x, y , rex, rcy ; 

B i nx , mi r.y , maxx , jnaxy ; 

ex. cy,dx,dy; 

l,t,r,b; 


' ■■ n 


object 


selected, just return 


if I obj 

return 


« NULL 

Or 


i 



clip to the view window rectangle, highlight the 
object, and draw rectangle around the object. 



getVii"-..: : dow,fcl ,it,tr,ib) ; 
prevRegion - setClipSect (window, l.t.r.b) ; 

SetAPen (window->RPort,HLPEH) ; 

point2dForward (world. viewTf, obj ->minj:, obj ->miny,&xl,&yl) ; 

pQJnt2dForwardlworld.viewTf ,obj->maxx,obj->jjiaxy,&x2,&y2} ; 

minx = doubleToLonglxU ; niny - doubleToLongiyl) ; 

maxx = doubleToLong(x2i ; naxy = doubleToLong{y2l ; 

drawObject (window, world. viewTf r obj 1 ; 

drawRect (w:r.ic rt -.-HPort,Eninx r miny,niaxx,riiiaxyl ; 



set up the real valued rotation rectangle, find the 

Lnt, the start angle, and the delta 

angle, then call the drag handler. 



rex = (obj-^rainx*obj->maxx)/2.0; 

rcy = |obj->miny+obj->maxy}/2.Qr 

rectxylO! - reccxylfi] = obj->minx - rex; 

rectxy[l| ■ rectxy|3] - obj->ntiny - rcy; 

rectxyfS] = r@ctxy[4] o obj->ciaxx - rex; 

re - -r v'~: = rectxyP] s obj->aaxy - rcy; 

rectxyfB] = rex; rectxy[9] = rcy; 

point 2dForta'ard!wor Id- vie^Tf ,rcx, rcy,&x,&yl ; 

ex = doubleToLong(x) ; cy - doubleToLor.giy] ; 

dx = world. pickX - ex; dy = world. pickY - cy; 

rectxyllQ] * startAng = atan2l-(doubleldy, (doubleldx) ; 

rectxylil] - Q.Q; 

handleDragt window, (void")rectxy,cx,cy,'l, 
rotateDrag, fcdx,&dy ]; 



erase object and rectangle, find delta rotation 
angle, and rotate the object. 



en ,window->RPort,BGPEK) ; 
drawObject Iwindow, world. viewTf , obj) ; 
drawRect (window- >RPort,:ninx r E.iny,Biaxx,maxy) ; 
rotateObject (obj,rectxy [10] -startAng) ; 

remove Che clip region A redraw ever/thing 



removed 1 i pp.ect ( window, prevRegion ) -, 
drewMl (window) ; 



/* find new world extent and reset pan gadgets 



setWorldExtent I &world |; 
setPanGadgets ! window ); 
return 0; 



* zoomDragd - drag /draw procedure for creating a 

zoom rectangle. 

void zoomDragt struct Window *window,void *obj, 
long oldDx.iong oldDy, 
long newDx.long newDy.iong code ) 
f 

struct RastPort *rp - window- >RPort; 
long *xy - (long'lobj; 

/* draw previous rectangle 

drawRectl rp.xy [ 1 ,xy [II, xy [2) ,xy [3] 1 ; 

if ( COde == BEGINDRAG II code == EHDDRAG I 

return; 

f* resize it and draw new rectangle *l 

xy[2] = xylO) * newDx; xy[3J - xy[l] + newDy; 
drawRectt rp,xy [0] ,xy U] ,xy [2] ,xy [3J ): 

) 

* moveDragll - drag/draw procedure for dynamically 

* moving a rectangle. 



void moveDiagt struct Window *windcw,void "cbj, 
long oldDx,long oldBy, 
long newDx,long newDy f long code I 



{ 



struct RastPort *rp - window->RPort; 
long 'xy = I long*) obj; 
long dx.dy; 

/* draw at previous location 

dravRect! rp,xy[0l ,xy [1] ,xy[2l ,xy|3J ); 

if ( code == BEGINDRAG I I code — EHDDRAG 
return; 

/• move it and draw at new location 

dx = newDx - oldDx; dy - newDy - oldDy; 

xy[D) += dx; xy|l) *^ dy; 

xy[2] t= dx; xy|3J += dy; 

drawRectl rp,xy [0] ,xy [11 f xy [2] ,xy[3] ); 



sizeDragt) - drag/draw procedure far dynamically 
scaling an object. 



void sizeDraglstruct Window "window, void *obj, 
long oldDx.long oldDyj 
long newDx.long ne*rfDy,long code ) 



( 



struct RastPort *rp = window->RPort; 
long *xy = Uong'lobj; 
int wd2,hd2; 

/* draw at previous location 

drawRecUrp.xy[0!,xy[ll,xy[2],xy[3]); 

if ( code ~ BEGINDRAG I I code == DJDDR^G ] 

return; 

/* resize the rectangle and draw it again 

wd2 - AES(newDx); hd2 = ABS(newDy)j 
xy[0] = xy[4| - wd2? xy[l] = xy[S] - hd2; 
xy[23 = xy[4] + wd2; xy[3] = xy[51 - hd2; 
drawRect ! rp, xy ( ] , xy [1 J , xy [2 ] , xy [3] ) ; 



rotateCragll - drag/draw procedure for dynamically 
rotating an object. 



vcid rotateDrag (struct Window •window, void 'obj, 
long oldDx.long oldDy, 
long newDx.long newDy.long code I 
{ 

struct RastPort *rp - window->RPort ; 

double *xy = ldouble*Jobj; 

double nev.'Ang,delcaAng F cosa, sina,x,y, tmp; 
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long pxO.pyCpx.py; 

int i; 

static double radl = degreesToHadiansd .0) ; 



find new angle values. If not first or last tine, 
and rotation is less than 1 degree, return, 
otherwise, draw the rectangle 



newAng = atan2 ( - (double) newISy, (dcubletnewDx) ; 
deltaAng = newAng-xy 110] ; 

if ( code != BEGINDRAG kk code !■ EMDDRAG && 
ABS (deltaAng) < radl ;■ 
return; 

point2dForward!world.viewTf , 

xy[8l+xyi0j,xyl9j+xyll],£x,&yl; 
pxO = doubleToLong(x) ; pyO = doubleToLong (y) ,- 
Movelrp^pxO.pyQ} ; 

fart i = 2; i < 1; i-^: I 
I 

point 2dForward [world -vierfTf . 

xy 1 6 ] . xy [ i ] , xy [ 9 ] . xy I i * 1 ] , &x , £y J ; 

px b doubleToLong (x> : py = doubleToLong !y 1 r 

Drawlrp,px,py) f 
} 
Draw!rp,pxO,pyO! j 

if ( Code ss BBGINDHAG I I code == ENBOaAG ) 
return: 



save angle values, rotate the rectangle around its 
center (0,0), and redraw it. 



icy 1 10] = newAng: xy[ll] = deltaAng: 

cosa = cos(xy[HJJ; sina * sin(xy[ll]l; 

tXp = cosa'xytOt - sina*xy[l]; 

xy[l] = sina*xy[Q| * cosa*xy[l]; 

xy[0] = tmp; 

unp - eosa*xy[2] - sina*xy[3}; 

xy[3] = sina*xy[2] • cosa*xy[3|; 

xy[2J = tmp; 

xy[4] = -xy(0]j xy[5] - -xyU]; 

xy£6] = -xyl2\t xy[7] = -xy[3]; 

point2dForward!worid.viewTf , 

xy!BI*xy[01,xy[9]*xy|ll,&x,&y>,- 
pxO = doubleToLonglx! ; pyO = doubleToLong {y) ; 
Move(rp,px0,py0) ; 

fot( i = 2: i < 7; i»2 J 
( 

point2dForward|world.viewTf , 

xy [ S I +xy | i ] , xy 1 9 1 + xy I i * 1 ] , &x , 6y ) ; 
px = doubleTaLongix) ; py ■ doubleToLong (y) ; 
Draw 1 rp - px , py ] ; 
) 

Draw(rp,px0,py0) ; 
J 

* moveGbjecr, ■( ) - raove an object by adding delca 

* coordinate values to the object- 



void moveObjectf object_t 'object, double dx, double dy ! 
i 

double *poly - object->poly; 

int i; 

for I i = 0; i < object->npts; i += 2 I 



po!y[i] +- dx; polyli+lj *■= dy; 
J 

object->rainx •- dx; object->miny + = 
object ->maxx *- dx; object-wnaxy *- 



dy; 
dy? 



resizeObject i i - resize an object using a scaling 
transform jnatrix. 



void resizeObject 1 object_t 'object, double sx, double sy ) 



I 



tran9form2_t tform; 
double *poly - object->poly? 
double tx, ty, minx, miny, naxx.maxy; 
int i; 



set up the scaling matrix - translate the object 
to the world origin, scale, then translate back 
td original location. 



tx - [object.-^minx-object->tEaxx] /2.0; 
ty - fobject->miny+abjec£->maxy! /2„0; 
mac.2dlnit( tfonn. matrix J; 
xnat2dTranslate( tform. matrix, -tx, -ty }; 
matSdScalel tform. matrix, sx,sy) ; 
mat2dTranslate( tform.matrix.tx.ty ); 

minx b miny = l,e38; 
maxx - maxy - -minx; 

for { i = 0; i < objeet-»npts; i += 2 ) 
( 

point2dForward(6t form, poly [i] f poly [i+1] , 

tpoly[il,£poly|i+l])i 

minx = HllUpolyfi] ,minx); rainy - MIN(poly[i+ll ,miny! ; 

roaxx - HAXtpoly [i] .rnaxx) ,* raaxy = MAX (poly [ i+1] ,maxyl ; 
} 

object->minx = minx; object->miny = jniny; 
Object->maxx = maxx; object->maxy - niaxy; 



• rotateObiectd - rotate an object using a rotation 

* transform matrix. 

void rotateObject [ ob;ject_t ■object, double ang ) 
t 

cransform2_t tform; 

double *poly - object->poly; 

double ninx^iny^maxx.maxy, tx, ty; 

int i; 



set up the rotation matrix to rotate object around 
its center - translate coordinates to center, 
rotate, then undo the translation 



tx - (object->minx*object->raaxx) /2.Q; 
ty = lobject->itiny*object->maxy) /2.0j 
mat2dlnit( tform. matrix ); 
rrat^dTranslatel tform. matrix, -tx, -ty },- 
raat2dRotate( tform. matrix, radiansToDegreea(ang) ) ; 
mat2dTranslatei tform. matrix, tx.ty }; 

minx e miny a 1 .e3B; 
maxx - maxy - -minx; 



for ( i - 0; i < object->npts; i t= 2 J 




Y-yoH^ \J\e,\pj 
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point2dFQrwa.rd [ it. form, poly [il r poly(itl] , 

£poly[i|,ipoly|i+l]]; 

minx = MIN(poly[i],minx); rainy = MlN(poly[i+l] ,miny> ; 

maxx = HAX(poly[i],tnaxxJ; maxy = MAX(polyli+l] ,maxy) ; 
) 

object->minx = minx; object->miny = miny; 
Gbj&ct->maxx ■ maxx: ob3ect->maxy ■ maxyj 



• eetClipRect (t 



set a clipping rectangle in a window 



struct Region 'setClipReet ( struct Window 'win, 
long minx, long miny, 
long maxx, long maxy ) 



• 



Struct Region •newClip; 
struct Rectangle clip; 

newClip = ( struct Region* INewKegionl I ; 



clip.MinX = minx; 
clip.MaxX - maxx; 



clip.MinY - miny; 
clip.MaxY = maxy,- 



OrRectRegion (newCl ip, iclip) ; 

return ( (struct Region MlnstallClipRegionl 

win->WLayer,newClip) } ; 



removeClipp.ect (J 



remove a previously installed 
clipping rectangle from a window 



void remaveClipRect Istmct Window 'win, struct Region *rgn 
i 

struct Region 'oldClip; 

oldclip - (struct Region *) InstallClipRegion) 

'.:::'.-■■>" .i, '■ i . :■■■:::■ ; 
it I oldClip ) 

DisposeP-egiontoldClip} ; 



drawAlKI - draw or redraw the world data, clipping 
to the window view rectangle 



void drawAlM struct Window "window ) 
{ 

struct Region "prevRegion; 

object_t 'obj; 

long 1, t,r,b; 

/■ clip to the view window rectangle 

getViewExtent ( wi ndow, £1 , it , £r, lb) ; 
pcevRegion = setClipRect (window, 1, t,r,b) ; 
drawAxis (window); 
SetAPen(window->RPQrt,DRAWPEH] ; 

for I obj = world, objects; obj; obj ■ obj->next ) 
drawObject (window, world. viewTf j obj | ; 

I* remove the clip region 

removeClipRect ( window, prevRegion ); 
I 

• eraseAlK) - erase the world data by filling the 

• window view rectangle with the 

• background color. 



void eraseAlll struct Window "window ) 
{ 

long 1, t,r,b; 

long fg,bg; 

getViewExtent (window, &l,&t,6r.fcbl ; 
£g = Uong)win4ow->RPort->FcPen; 
bg = (lQng)window->RPort->Bc.Pen; 

Set APen (window- >RPort,0] ; £etRPen(window->R?ort,OJ ; 
RectFill(window->RPorc,l,t,r,b) ; 
£etAPen(window->RPort,fg) ; SetBPen(window->R?ort,bg) ; 

• drawAxisI) - draw the x,y world coordinate axes. 

void drawAxisI struct Window 'window! 
I 

double xp.yp; 

long 1, t,r,b,cx,cy? 

/• get the view window corner coordinates. 
getViewExtent (window, si, it, kr.&bK* 



SetAPen|window->RPort,AX.ISPEH) ,- 



find world center in view coordinates and draw 
horizontal & vertical lines through the center 
coordinates. 



point2dForward{ world.viewTf ,0.0,0.0,Sxp,&ypl ; 
ex = doubleToLong (xpj; cy = doubleToLong iyp) ; 
if ( t < cy && cy < b ) 
( 

Move I window- >RPort, l„cy) ; 

Draw[window->RPortjr f cy I ; 
i 

if I 1 < ex && ex < r ) 
( 

Move|window->RPort,cx. t) ; 

Drawlwindcw->R.Port,Cx,b) ; 



* £indObject() - search for an object at the given 
+ world coordinates* 

object_t *£indObject( object_t 'objList, double x, double y, 

double eps i 
i 

object_t *obj; 

for I obj e objList; obj; obj = obj->next ) 
if ( point2Poly[ obj.x.y ) <- eps } 
return obj; 

return HULL; 
) 

* point2PolyU - find smallest distance from a point to 

* a polygon 



■double point2Poly( object_t "obj,double x, double y ) 
t 

double 'poly = obj->poly; 

double xl,yl r x2,y2; f* 

double distSq, rainDistSq: /* 

double xStar.yStar; /* 

double tl.deltaX.deltaY; 

double num,denom; 

int i; 



line segment endpoints *i 
squared distances */ 
nearest points on seg */ 



xl = poly [0]; yl = poly[ll; 
if (x» xl &fr y ^- yl I 
return 0.0; 

rainDistSq - 1 .e38? 

/* find distance from point to each line segment 



for ( i = 2; i < obj->npts; 

( 



+ = 2 | 



x2 ■ polyli]; y2 a poly[i»l]; 
if ( x — x2 && y — y2 | 
return 0.0; 

deltaX = x2 - xl; deltaY ^ y2 - yl; 
denorr = deltaX'deltaX * deltaY'deltaY; 



if ( denom < l.e-6 
continue,- 



num s deltaX*(x^xl 
tl = num / denom; 



I ," segment is a point 
♦ deitaYMy-yl); 
/* x,y is left of segment 



*7 



if ( tl < 0.0 
{ 

xStar - xl; yStar ■ yZ; 
} 

else 

if 1 Cl < 1,0 ) /• x.y is on the segment V 
( 

xStar = xl -r tl*deltaX; yStar - yl * tl'deltaY; 
} 

else /' x,y is right of the segment*/ 

{ 

xStar s x2; yStar - y2; 
) 
distSq = UStar-x)'(xStar-x) * (yStar-yl *(yStar-y) r 

if [ distSq < minDistSq ) 
rainDistSq - distSq; 

xl = *2; yl - y2; 
1 
return sqrt I minDistSq \ j 
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* drawQbjectl) - transform world coordinates to view 
coordinates and draw a polygon. 

-.-.--- = ==== = = = == = = = == = = ------ = = = =:_=___________=;=,_,____*/ 

void drawQhject [struct Window *windcw,transforpi2_t 'tForm, 

object_t 'object) 
I 

double "poly = object->poly,' 

doable tK,ty; 

long px.py; 

int i; 

p0int2drorward( tFora, polyLQJ, paly [1] ,&tx, sty ) ,- 
px = doubleToLong !tx] ; py b doubleToLong (ty) ; 
Hovel window->RPort,px,py 

for ( i = 2; i < object->npts; i ♦■ 2 ) 

( 

point2dForward( tForrupolyti] ,poiy(i+lj ,SLtx,ity ); 

px - doubleToLong Ux) ; py = doubleToLong (ty) ; 
Drawl window->Rport,px,py 1 ; 



drawRectd - draw a rectangle using current pen i, mode. 



void drawRectt struct RastPort 'rp, 

long xl.long yl.long x2,long y2 ! 
{ 

Move! rp, xl.yl > ; 

Bc_V< rp H x2»y2 ) ,- 
Drawl rp,xl,yl ); 



Drawl rp,xl,y2 ) 

Drawl rp,x2,yl ) 



} 
* setWorldExcentfl - find and set world min/max values 



void BetWorldBttentl wcrld_t 'world ) 
{ 

object_t *obj; 

world->minx = world->rainy = l.e3£; 
world->paxx = world->maxy = -l.e3B; 

fori obj = world->objects; obj; obj = obj->next 1 
{ 

>. T Drld->ininx = HIK(world->niinx,obj-5-minx) ; 

world->miny - HIN lworld->niiny,obj->minyj ; 

world->niajcx = HAX|u-orld->maxx,obj->naxx) ; 

world->~axy = HAX(world->maxy l obj->naxy] ; 



f getViewExtent | ) 



return view window min/max values. 



void getViewExtent Istruct Window *win r 

long *l r long *t,long *r,long "b } 
{ 

•1 = Uanglwin-j-RorderLefc + 1; 

■r = (long) [win-:-Width - win->BorderRight) - 1; 

*t = (longlwin->BorderTop + 1; 

'b - (long) twin->Height - win->BarderBatto*n) - lj 
) 

* handlelnput ( 1 - monitor user input until end action 



void handlelnput ( struct Window *window 1 



extension pointer 



inEuiExtensi.on._t *ext; 

myMenuItc-r u t *mi; 

struct IntuiHessage *msg,mcopy; 

struct Gadget ';_: - 

for [n) 
( 

Wait( 1 t< window->UserPort-Mnp_SigBit ): 



while I msg 



[struct IntuiMess&ge *) 

GetHsg(window->UserFort) I 



©copy = *»sg* 
ReplyHsg I msg 1 ; 



Get our extension data from the Intuition 
object, then call the event handler if 
there is one. 



it 1 racopy. Class -- MENUPICK &£. 
mcopy.Code I- MEKUliULL 1 



-yMenuIteir_t * ) ItemAddress 



(window- >Ker.uSt rip, [LONGlDCOpy.Code) ; 
ext - fi-ii->extensf 
) 

else 
if { tncopy. Class ■* GADCETDOWN II 

mcopy. Class =- GaDgetUp I 
( 

if ( gadg = Istruct Gadget') -copy. lAddress } 
ext = [intuiExtens).art_f)gadg->UserData; 
J 
else 

ext t I intuiExtension.t*! window- >UserData; 

if I ext && ext->handler | 

if I (*exL->handler) l£mcopy,ext->data) 1 
goto allDcne; 



I" ercpty the message Ojueue ■/ 

allDone: 

while! msg - (struct IntuiHessage ') 

GetMsg (window- >UserPort ) ) 
ReplyHsg I nsg ) ; 

* handleDragl) - process input while user 'drags' an 

* object . 

* TOTE; HewWindow must have the REPORTMOUSE flag set 

(Flags) for this procedure to wort correctly. 



void handleDragl struct Window 'win, void "object. 

Long startx,long starty^long moveEps, 
void PdragDraw) I) , long "dx, long *dy ) 



( 



struct RastPort 'rp - win->RPort; 

struct IntuiHessage *msg; 

uns igned long event , oldflags , newFlags ,- 

unsigned short code,' 

long oldMode, oldPen, oldDx , oldDy ; 

long testx, testy, Dldx.oldy,- 

long newx,newy: 



save current IDCMP tlags and set up for HOUSEBUTTOMS, 

HOUSEMO'/E, and HEJTJVEHIFY events. 



if I iroveEps <~ ) 
ir-oveEps = lj 

oldx = startXf oldy = startyj 
oldDx - oldDy ^ 0; 

oldFlags = win->ICCHPFlags; 
newFlags = HOUSEBlTrTONSlHOUSEKOVS? 
if | win->HenuStrip ) 
newFlags 1= MENUVERiFY; 

ModifylDCMPf win, newFlags ): 



save rastport pen £ drawmode, then set pen to 
background pen and irode to COMPLEMENT 



oldHode - Ucnglrp->DrawMode; oldPen = (long)rp-*i-gPenr 
SetDrHd(rp,CC^flEHENT) j 5etA?en(rp,BGP£i3) i 



get drag started with initial call and process 
nags until SELECTCOKR event occurs. 



I *dragDraw) [win , object f o , o , o , o , 3egikdrag) ; 

while I TRUE ) 
( 

msg = (struct IntuiHessage * J GetMsg (win->UserPort>; 

if ( ! msg ) 
continue; 

/* get values we need and reply to the message '/ 

(long)msg->MouseX; newy e [long)n!sg->HouseY!' 



newx 

testx = ftBSInewx - oldx] 
*dx = newx - Btactxj 
event = psg->Class; 



testy = ABSCnewy - oldyl? 
*dy = newy - starty; 
code - msg->Code; 



if we got a iftenu verify event, tell Intuition 
to cancel it. 



if ( event == MENUVERIFY } 
-:Sg->C0de = MHIUCAHCEL; 
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RepiyMsgi (struct Mcssage*}nisg >: 



if cursor moved by specified amount. ni_- the 
dragdraw procedure, then save delta v.; 



IE [ tesnx >- tnoveEps I I testy >= moveEpn J 
I 

CdragDraw) (win, object ,oldnx,oIdDy, "dx. "dy,Q] 

oldx = nevx; oldy - newy; 

oldDx - *dx; oldDy = *dy; 
I 
if ( code « SELECTDOWN ) 

break; 



/■ call dragDraw to finalize the drag 

if 1 oldDx != *dx II oldDy != *dy ) 

fdragDraw) (win, object. oldDx, oldDy. *dx, *dy,QJ : 

CdragDrawl (win. object, "dx,*dy. *°*. 'dy.EHDOaw;] ; 

/■ restore everything */ 

SetDrMd(rp.oldMod^) ; SetAPen{rp,old*en) ; 
ModifylDCMHwin.oldFlags) r 
1 

* openLibsi! - open libraries 

9 .>...> E ==========± : ±==== ==»s7~-=-== ====== = = = = =========■; 

int openLibsl void ) 
i 

IntuitionBase = (struct IntuitionBase *)OpenLibrary{ 

"intuit ion. library -,IN-ruiT:ON_REV) j 



GfxBase - (struct G: xBase •JQpenLibxary 

"graphics. . 11 . - -: r:-_7T 

LayersBase = [struct LayersBase 'IDpenLibrary < 

■layers. library", OL] ; 
retumi GfxBase && IntuitionBase && LayersBase )r 



void closeLibs! void 1 

: [ntuition&ase t ClcseTjibraryf Intuition! 

it ( GfxBase ) CloseLibraryfGLxSsse) ; 

:- LayersBase J CloseLibrary(LayernBasel r 

I 

/•iwwmnmimnatisBssssu 

• dispUyWindowO - display an intuition window 



struct Window *di splayWindowtint L,int t»int w, inC h, 

char *naz-e, struct Gadget *ga<31 
{ 

i ■ HewWindow new; 

new.LettEdge - 1; now.TopEdge = tj 
new. Width = w; new. Height = hr 

new.DetailFen = -1; new.BlockPen = -1; 
new. Title = name; 

.. Lags = WIHDOWCLOSEIWXffiXWKlAG S*ttRT_REFRESHl 
ACTIVATE WINDOWS '■:■ :Tr ^:.V;-; 
new.IDCMPFlags = CLOSEWDflXWIREFW 

HENUPICK I H0USE3UTT0NE I GADG&TUP; 
Gadget ■ gad; new.CheckHark - HULL; 
■..;. Icb ISO; new.HinHeight = 100 : 

new.KaxWidth = 640; new.MaxHeighL = 100; 

new. Type = wbenchscreen ; 
retural struct Window * a ... inew] ); 
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Could You Design and Program A 
Complete Amiga Application ? 

You learned to program the Amiga's user interface in Paul Castonguay's 
Programming the Amiga's GUI in C— Parts I-II (ACs TECH\\.2&\13) 

You explored graphics system mathematics & algorithms in Forest Arnold's 
CAD Application Design— Parts I-II (ACs TECHV12 & V1.3) 




You experimented with AmigaDOS I/O in Bruno Costa's 
AmigaDOS for Programmers (ACs TECH Premiere Issue) 



M 1 



You developed an Online Context-Sensitive Help System in Phil Kasten's 
Adding Help to Applications Easily (ACs TECH V 1 .2) 
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Put the pieces together. Anything is Possible! 



For Back Issues or Subscriptions call 1-800-345-3360 (credit card orders only, please) 
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C MACROS 



for ARexx] 



? 



by David Blackwell 



ARexx 

Since its release, ARexx has become increasingly popular 
and the number of commercial programs supporting ARexx 
continues to grow. In fact, Commodore has licensed ARexx for 
inclusion with the AmigaDOS 2.0 operating system. ARexx is 
here to stay, and it will have a continued impact on all types of 
software developed for the Amiga. This can be attributed to 
the way ARexx macros are used to extend the applicability of 
an existing program or to combine several programs into a 
user-customized environment. 

ARexx macros can be called by a host program to perform 
a specific task the program is either unable to perform itself or 
performs inefficiently. This is the way an ARexx macro can 
extend a program's utility. This capability of ARexx makes it 
possible for programmers to highly specialize the host 
program's operation. Programmers can optimize their code for 
speed of execution and reduce its size. Users can then add the 
frills or features they want or need through the addition of 
ARexx macros. All the programmer needs to do is include the 
capability in the host program to call ARexx macros and 
process their responses: in other words, an ARexx interface. An 
ARexx interface is relatively simple to include in the host 
program and usually increases the code size by about 2-3K 
(most likelv less than the size saved by optimizing the 
program's operations). 

The most advanced ARexx macros are written to combine 
several application programs into a totally customized 
environment. One macro — or perhaps a group of macros — 
directs the efforts of several programs in any way the user can 
imagine. This capability of ARexx macros staggers the imagi- 
nation and has yet to be fully realized. As the number of 
programs supporting ARexx increases, and as users become 
better acquainted with ARexx, these macros will become more 
commonplace. The release of AmigaDOS 2.0 should greatly 
accelerate this eventuality. 



ARexx and C 

Although ARexx is powerful and easy-to-learn, some of us 
don't have the time or the desire to learn a new programming 
language. We are quite happy with the programming language 
we currently use. Fortunately, if your favorite language is C, 
you can still have access to the power ARexx provides (Modula 
2 and assembly language interfaces are also possible). As a 
matter of fact, the ARexx interpreter is a shared library (also 
known as a resident or system library). This library allows 
access to all the essential ARexx functions. There are two ways 
to access these functions using C: glue routines and pragmas. 

Glue Routines 

By using the glue routines provided on the ARexx 
commercial disk, it is a simple matter to call these functions. 
When you call any ARexx system library function, you are 
actually calling a small assembly language routine. This 
routine is called a glue routine. The glue routine pulls the 
arguments off the stack, puts the arguments into the appropri- 
ate registers, puts the library base pointer into the a6 address 
register, and then calls the Library routine with the proper 
library vector offset. As you can imagine, these glue routines 
add a little overhead to your program in terms of size and 
speed. If you have an ANSI C compiler, you have another 
option: use pragmas. 

Pragmas 

I prefer to use pragmas since they neither increase the size 
of the program, nor slow it down. The ANSI standard allows 
for extensions to the C language in a controlled manner using 
pragmas. By using a pragma, the C compiler will generate 
code to call the library function directly without pushing any 
arguments onto the stack or using a glue routine. All argu- 
ments are loaded directly into the proper registers and the 
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library's base address is placed in the a6 address register. Then 
the function is called using the proper library vector offset 
(Aztec C-style pragmas for the ARexx functions I used in my 
example programs are included in the Graphics. h file). 

Whether you use glue routines or pragmas, you still have 
the same access to the ARexx functions using C. The only 
difference will be in code size and speed of execution. There 
are, however, disadvantages and advantages to using C rather 
than ARexx itself. 

Disadvantages 

Programming a macro in C will require more code than 
using ARexx: 

address 'hostname' 

in ARexx, for example, does the same thing as, 

Forbid (); 

if ( fnostport = FindPort (KOSTPORTHSKE) ) == } 

( 

PermitO; 

return ( <error number> ) ; 
) 
Permit ( ) ,- 



Also, the ARexx interpreter automatically allocates any 
message ports your macro requires. This operation is totally 
transparent to the ARexx macro programmer. On the other 
hand, in C vou are required to set up your own message ports, 
keep track of any message port activity and dispose of the 
message ports when you no longer need them. This difference 
alone can generate a lot of code. At a minimum, you will need 
four functions to manage your message ports: one function to 
open the message port, one function to get messages from the 
message port, one function to send messages to another port 
and one function to release the message port when you're done 
with it. There is a way to turn this particular disadvantage into 
an advantage; however, we'll discuss that later. 

Perhaps one of the biggest disadvantages of C is the lack 
of a built-in tracing facility. With ARexx you have eight 
distinct tracing options, and you can even selectively debug a 
section of your program while all other sections execute 
without tracing. Perhaps the most missed feature is the 
interactive tracing offered by the ARexx interpreter. 

With these apparent disadvantages one may question the 
use of C in the first place. Well, in my opinion, the advantages 
of using C far outweigh the disadvantages. 

Advantages 

Perhaps the most noticeable advantage is the execution 
speed of a macro written in C. For small macros this might not 
be too apparent, but when you start writing sizeable, mature 
macros you will begin to notice a marked difference in their 
performance. To be fair, no interpreted language can match the 
speed of a compiled language. When you start expecting a lot 
from your macros, you will really appreciate the increase in 
speed. 



Also, the more you begin to expect from a macro, the more 
you will want the power and control that C affords you. Not 
only do you have all the access to the high-level Intuition, Exec 
and Amiga DOS routines that ARexx provides but, if you need 
it, you have access to the low-level Graphics and AmigaDOS 
routines as well. You decide just how much control over the 
Amiga you can handle. Sometimes, too much power in the 
wrong hands is a dangerous thing. However, an experienced 
programmer can reallv take control of the Amiga and do some 
amazing things with an ARexx macro written in C. Besides 
speed and power, code integrity is a real concern for some 
programmers. 

If you are really proud of what you have accomplished 
with your macro, and program code integrity is a high priority 
of yours, you will really appreciate the fact that C macros are 
extremely difficult to tamper with. In fact, the only way your 
work can be tampered with is if you release the source code 
with the executable program. After you have spent days, 
weeks or perhaps even months working on a macro and 
getting it just as you want it, the last thing you want to do is 
release it into the public domain and instantly have in excess of 
100 different versions of it out there, with a multitude of 
various users requesting help from you or blaming you for a 
problem you didn't even know existed. With code integrity, alt 
the improvements and additions to your macro must go 
through you. And that's how it should be for any program that 
the original programmer intends to fully support. But enough 
with this discussion on the disadvantages and advantages of C. 
Let's move on to actual macro development in C. 

Macro Development 

Now for the hands-on stuff. Let's get started actually 
examining a macro written in C. This macro (actually two 
macros were prepared for you) will be designed to work with a 
program that has a message port and can process ARexx 
messages. If you received the Premiere issue of AC's TECH, 
refer to the article by Dan Sugalski concerning interprocess 
communication with ARexx. 1 have converted Mr. Sugalski's 
ARexx macros to C as a comparison of the two languages. If 
you didn't get the Premiere issue but have the disk for the 
second issue, these programs can be found on that disk in the 
archive directory under the name "IPC.lzh". You will want to 
look at the Example3.rexx and Example4.rexx programs. (If 
you don't have either the Premiere issue or the disk to the 
second issue, and are extremely interested in seeing the 
difference between the two languages I'm sure there are back 
issues available.) 

One of the first things you need to do in a C macro that 
will access the ARexx system library is to declare a Global 
variable to hold a pointer to the base address to that library. 

struct RxsLib *?.exxSys3ase; 

That should do very nicely. The name must be exactly as 
shown. When you make the call to the OpenLibraryQ routine, 
you must cast the return value to the correct structure or your 
compiler will complain. 
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RexxSysBase = (struct RxsLib *) OpenLibrarylRXSNAME, OL); 

The above example is the proper way to accomplish that 
task. This library must be opened before you attempt to call 
any of the ARexx functions, unless you enjoy visits from the 
Guru. 

1 call a function to open all the libraries 1 will use in my 
program similar to the function described by Paul Castonguay 
in his article, "Programming the Amiga's GUI in C, Part I," in 
the second issue of AC's TECH. This is a good structured 
approach to programming reusable functions which only 
require slight modifications to be used in any program you 
write. This approach will be very important in writing C 
macros since many of the routines required to get set up and 
communicate with another program can be written once and 
used repeatedly to save programming time. In fact, I used that 
very approach on the two macros I converted as you will see 
when you examine the code. After opening the ARexx system, 
you are ready to open a message port. 

Now a major design decision must be made. Do you want 
to allow multiple copies of your macro to run at the same time, 
or do you just want one copy running at a time? How you 
open your message port will determine this. For my example 
program I chose single execution. In that design methodology, 
you first check for the existence of a message port by the name 
you want yours to be. If one exists, you return an error 
condition and terminate execution of the macro. Under the 
multiple-copy methodology, you would simply add a unique 
suffix to each new message port name so each could be easily 
distinguished. 

Because of the importance of a message port to the 
successful operation of an ARexx macro, your routine that 
opens your message port must inform the main program 
whether it was successful. If it was successful, then execution 
continues as normal. If it was unsuccessful, then the macro 
should exit gracefully. Also, here is where using C can be an 
advantage to ARexx opening a message port for you. With 
ARexx, vou can only communicate through one message port 
at a time. Using C, you can communicate through as many 
message ports as you like all at once, and you will be able to 
pull it all off much quicker than ARexx. 

Opening the ARexx system library and opening a message 
port are the most basic setup requirements. Your particular 
macro may require a more elaborate setup; however, that is up 
to each individual programmer. After setup, though, macro 
operations must commence. 

Macro Communications 

Macro operations consist ol communications between 
your macro program and the host program with which it was 
designed to operate. Here another major design decision must 
be made. This time it is a choice between either synchronous or 
asynchronous communications. Simply put, it is a choice 
between sending a message and then waiting for a response 
before doing anything else (synchronous), or sending a 
message and continuing with other processing, occasionally 
checking your message port for a response or waiting on a 
signal from your message port after all other processing you 
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can do is completed. Also, you need a response before you can 
continue (asynchronous). I chose asynchronous communica- 
tions for my example programs. I just don't like waiting 
around for a response when there are other things I could be 
doing. Here is where you have another advantage over a 
macro written in ARexx. ARexx uses synchronous communica- 
tions whether you want it or not; C gives you a choice. Once 
the decision is made concerning which type of communica- 
tions you will use you can start designing your message-send 
function. Again, a fairly standard function can be designed 
here so that, with a little modification, it can be used in any 
program you write in the future. 

Here are the design considerations I used when develop- 
ing my message-send function: 

1. The function should receive as few 
arguments as possible, 

2. The existence of the receive port should 
be checked. 

3. In case of error, all memory allocated 
should be released. 

4 If all goes well, send message to receive port. 

And here is the code I used to satisfy my design consider- 
ations: 
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void arexxsendlSTRPTR catmandstr) 
( 

struct MsgPort *sendport; 

struct RexxMsg "rexxmsg; 



if (Mrexxmsg - CreateRexxMsg ( (struct RexxMsgPort *]Graphl,\ 
(STRFTR) 0, (STRPTR) HYPORT1))) 
goto rs_exit; /* not able to create a message */ 

if [ ! (rexxmsg->rtn_Args[Ql = CreateArgstring(caimandstr,\ 
(ULONGI strlendchar *) comandstr) ) ) ) 
{ /* not able to create argstring so delete */ 

DeleteRexxMsg(rexxmsg) ; /* the RexxMsg and */ 

goto rs_exit; /* leave the routine */ 



rexxmsg->rm_Action = RXCOMM; /* indicate a ccamand */ 
Forbid I); 

if (Ksendport = FindPort(MYPORTl))) 

I 

Permit (1; /* unable to find the port so delete the */ 
DeleteArgstring(rexxmsg->muArgs[0]); t* Argstring */ 
DeleteRexxHsglrexxmsg) ; /* and the RexxMsg */ 
goto rs_exit; /* and leave the routine */ 



/* everything went ok so send the message */ 
PutMsg(sendport, (struct Message *) rexxmsg) ; 

Permit ( t ; 



return; 



) 



The CreateRexxMsgQ function does just what it implies: it 
creates an ARexx message structure to communicate with 
other ARexx-compatible programs. The first argument is a 
pointer to the message port structure to use as a reply port for 
the message, and the last two arguments are pointers to null- 
terminated strings. The first string is the default file extension 
to be used when requesting ARexx to load and execute a 
macro, and the second string the initial host address. This 
function allocates all the memory necessary to create the 
message structure. The CreateArgstringQ function creates an 
ARexx argument string using the supplied string. The first 
argument is a pointer to the null- terminated string to use, and 
the second argument is the length of the string. This function 
also allocates all the memory that it needs to create the 
argument string structure. 

You may have noticed that 1 disable task-switching and 
check for the existence of the send port before I attempt to 
actually send the message. This is very important on a 
multitasking computer where programs can terminate as 
quickly as they began. By disabling task switching and 
ensuring that the program is actually there before sending the 
message, you avoid a lot of problems and even a possible Guru 
visit or two. If the receive port has closed, I release the memory 
1 just allocated by using the DeleteRexxMsgQ and 



DeleteArgstring() functions which use the pointers returned by 
the earlier functions and return to the calling program. 

Finally, if all goes well the message is sent on its way to 
receive prompt attention. The last thing 1 do before returning is 
enable task-switching again. 

A small task for you: if I had decided on synchronous 
communications, how would I have to modify this function to 
achieve that? You could even have two send functions — one 
synchronous and one asynchronous — in the same macro, and 
use the one best suited for each particular command. Also, 
how would you modify this function so that it returns an error 
status to indicate whether it was successful or not? 

In my small examples I don't really care about any return 
values; in fact, I don't even check for any, much less set any 
return values. On the other hand, in an important macro you 
would always check the return values. You would check the 
rm_Resultl field of the RexxMsg structure to see if your 
command or request was successfully executed. If you 
requested a return string from the host, you would copy it to a 
safe place using the string pointer in the rm_Args[0] field. 
After you copy the string to a safe place, you can release the 
argument string and message structure memory. You would 
then take appropriate action depending on the value you 
extracted from the rm^Resultl field. These are the absolute 
basics to macro operations. No matter how elaborate your 
macros become, these are the basic building blocks of all 
macros. When your macro is finished with its task, what do 
you do then? 

Macro Shutdown 

This should answer your question — you close up shop 
and terminate operations. That is as easy as deleting all 
memory allocated during macro operations, closing down 
your message port, closing any windows opened and then 
closing the ARexx system library. It is always a good idea 
when deleting memory and closing your message port to 
disable task-switching and avoid the possibility of other 
programs trying to send you messages while you are attempt- 
ing to close down. Just don't forget to enable task-switching 
again before you terminate execution of your macro. My 
Release_Port() function demonstrates one way to do this: 

void Release_Port (void) 
I 

struct RexxMsg *rtnmsg; 

ForbidO; 

/* delete all outstanding messages */ 

while (rtnmsg = (struct RexxMsg *) GetMsg(Graphl) ) 

{ 

if (rtnmsg->rm_Kode.;rn_Node.ln_Type == KT_REPLKKSG) 
! /* a reply to one of my messages so delete it */ 
DeleteArgstring (rtnmsg->rm_Args i0] ) ; 
DeleteRexxMsg (rtnmsg) ; 
)else{ /* not one of ray messages so reply to it */ 
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rcraisg->rm_ResuH;l = RC_ERROR; /* indicate error */ 
ReplyMsgl (struct Message *|rtnmsg); 



DeletePort(Graphl); /* delete the port */ 

Permit! I ; 
return; 



Running the Macro 

ARexx macros are normally executed from the CLI by 
typing the command "rx" followed by the program name and 
any arguments. C macros do not need to be preceded by the 
"rx" command. They can be executed directly from the CLI 
prompt. This raises a small problem if you are writing the 
macro to be executed by a host program directly rather than 
executing the macro from the CLI prompt. Host programs run 
macros by sending a message to the ARexx-resident process 
requesting that the macro be executed. All ARexx macros are 
basically ASCII files that are interpreted and executed by the 
ARexx interpreter. On the other hand the C macro, once 
compiled, is an executable program. The ARexx interpreter 
cannot execute a compiled C macro. If you are writing your 
macro to be executed by a host program, you will need a small 
ARexx boot program to start your compiled C macro. This is 
not much trouble, and you can use the same small boot 
program to start other C macros you write. The following code 
is all you need to have an ARexx boot program: 

/* ARexx boot program for the compiled Graphicsl C macro */ 

address command "Graphicsl" 

exit 

That's all it takes to have your C macro executed by 
ARexx. To use the same code with other C macros, simply 
change the program name in quotation marks to the name of 
the program you want executed. If your macro requires 
arguments, include them in the quotation marks. Perhaps if the 
use of compiled languages to write ARexx macros increases, 
commercial programmers will start including the option to 
execute ARexx macros directly without using the ARexx 
interpreter. 

Conclusion 

As stated at the onset of this article, ARexx's popularity 
continues to grow. By becoming familiar with it, you can more 
easily customize those commercial programs you purchase 
which have ARexx interfaces. You will get a bolter end product 
by adapting the feel of the program to your personality. 

You can use the ARexx interpreted language to write your 
macros, or you can use C when you need the advantages of 
speed, power, and code integrity. The capability to open 
several message ports and choose asynchronous communica- 
tions, if needed, cannot be overlooked. 

Although using C requires you to write more code, the 
positive side to that is if you use structured programming 
techniques, you can reuse the functions repeatedly with just 
slight modifications. This will save you time in the long run 



and results in making programming in C almost as easy as 
programming in ARexx. Also, if you are already familiar with 
C, you save the time of learning a new language. 

Other Notes 

These example programs were not meant to show you all 
the ins and outs of C macro programming for ARexx, but to 
get you started and then let you learn the finer points yourself. 
These programs have no value other than as instructional 
examples. 

I realize that some may be confused with my encourage- 
ment of structured programming while at the same time 1 use 
the abhorred goto statement throughout my programs. This is 
simple to explain. I believe highly in structured programming, 
but 1 also believe that as intelligent beings, we should not be 
stifled bv stringent inanimate principles. I also disdain the 
undisciplined use of the goto statement, and 1 believe that I use 
it in a very structured manner. I attempt to use a programming 
style that is easy to use and understand. 1 will show some 
alternatives to my use of the goto's as a comparison and 
contrast and let you decide which you think is better: 

Alternative 1 - The If-Then-Else ad infinitum 

if (no error! 

continue processing 
i£ (no error) 

continue processing 
it |no error) 

continue processing 
ad infinitum 
else 

set error condition 
else 

set error condition 
else 

set error condition 

These things can soon indent themselves right off the 
screen and create a real mess when you try to print them. 

Alternative 2 - The multiple exit points from a routine 

it (error) 

display error 

exit program/ function 
endif 

if (error) 

display error 

exit program/ function 
endif 

continue processing 

This is similar to my use of the goto statement but, in my 
opinion, it is a violation of the basic structured programming 
premise that each program or routine should have only one 
entry point and one exit point. However, each programmer 
eventually decides for himself or herself which style they feel 
more comfortable with. 
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VBRMon 

An Interesting and Unusal 
Assembly Language Monitor 




by Dan Babcock 



VBRMon is an exciting utility that will help you more 
fully explore and take control of your Amiga. It is a machine 
language monitor like many others, but it has some very 
interesting and unusual properties.,. 




that this routine is universal — it can replace any or all of the 
exception vectors {except bus error). A special routine for each 
vector is not necessary. Figure Two shows the stack arrange- 
ment upon entering this routine. 



The Concept 

VBRMon takes advantage of the vector base register 
(VBR) present in the 68010 and higher 68000-family CPU's. The 
vector base register, quite simply, allows one to move the 
exception vector table {always the lowest IK of memory on a 
plain 68000) anywhere in the 32-bit address space. (See Figure 
One for a map of the exception table.) Why is this useful? 
Consider that all (or almost all) software assumes that the 
exception table is always located at location 0. The relocated 
vector table, therefore, is essentially protected and we can 
intercept all exception activity (most important, interrupts). 
That means that whenever an interrupt occurs (which is quite 
often on the Amiga!) our devious little exception handler can 
grab control. In practice, this exception handler will check to 
see if both mouse buttons are pressed. If so, it will invoke a 
machine language monitor to enable the examination of the 
currently running program(s). if not, it simply jumps to the 
corresponding "real" vector, located in low memory. Thus, it is 
almost totally transparent to the host software. 



Handler : 



1 




. i •• rs 


"';-■': 


be 


saved 


t 


-■■'■' 


ill) 






, f- 


■ -* 




- , n 1 QT - 


tat 


cleans 


ledds 


4 Co 


;r 


. 


le on 


•010 


or 


higher] 



t ;!* programrer know his code works; 



1 




Typical Exception "Wedge" 

To illustrate the concept, the following is a typical 
exception "wedge" routine, which will be executed whenever 
an exception (or an interrupt, which is a class of exception) 
occurs. It is a simplified version of the one in VBRMon. Note 



Requirements 

First of all, VBRMon works best if you have a 68010 — no 
surprise there! However, it does provide some utility on plain 
68000 machines. It will still trap gurus and the DebugO vector, 
and it permits you to use a "GOMF button" (i.e., an NMI- 
generating device) to invoke VBRMon. Second, it works best 
with 1MB of Chip RAM available. Normally the program code, 
its data, and the screen display are kept in the upper 512K of 
Chip RAM, leaving all the lower 512K available for the use of 
the host application (e.g., game), and also facilitating reboot 
survival. 
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Figure One (Source: Programming The 68000 by Steve Williams) 



How To Start It 

VBRMan may be started by 
simply typing "vbrmon" at the CLI 
prompt or by clicking on its icon — yes, 
it supports Workbench! You will then 
be asked to enter addresses for the 
program code, data area, and screen 
memory, if you have 1MB of chip 
memory, the defaults should prove 
acceptable. It is also possible to specify 
the desired options as command line 
parameters, like so: 



Vector 


Address 


Function 







so 


RESET initial SSP (supervisor stack pointe-) 


i 


S4 


RESET initial PC (program counter) 


2 


se 


Bus error 


3 


sc 


Address error 


4 


S10 


Illegal Instruction 


5 


S14 


Divide by zero 


6 


S18 


CHK instruction 
TRAPV instruction 


7 


SIC 


8 


S20 


Privilege violation 


9 


S24 


Trace 


10 


S28 


Line 1010 emulator 


11 


52C 


Line 1111 emulator 


12-14 


S30-S38 


Unassigned (reserved) 


15 
16-23 


S3C 


Uninitialized interrupt vector 


S40-S5C 


Unassigned (reserved) 


24 
25-31 


S60 


Spurious interrupt 


S64-S7C 


Level 0-7 autovector Interrupts 


32-47 


S80-SBF 


Trap 0-15 vectors 


48-63 


SCO-SFC 


Unassigned (reserved) 


64-255 


SI 00-5400 


User Interrupt vectors (not used) 



VBRHon Program_addrass Screen_address Data_address 

The addresses should be entered in hex, without a preceding S. 
If all goes well, you will be congratulated with the message, 
"VBRMon initialized successfully. Press both mouse buttons to 
invoke." If you have only a plain 68000, you will receive a 
somewhat less satisfying message. 



Command Rundown 

Press the HELP key for a command overview while in 
VBRMon. Here's a brief explanation of the commands: 



Function: AsBentole 

Syntax: A <starting ad&ress> 



Using It 

Assuming that you have a 68010 or higher, you may now 
invoke VBRMon by pressing both mouse buttons at any time. 
The vector that was trapped will be displayed (e.g., "VBRMon 
invoked by vector $6C") along with a register dump, including 
the current program counter, and INTENAR and DMACONR. 
You are now in control of a powerful machine language 
monitor with which you may examine and alter the state of the 
machine. Use the control key to pause screen output. Delete 
places the cursor at the top of the screen; shift-delete clears the 
screen. Escape will abort most commands. Use shift-cursor-up 
and shift-cursor-down to access previously entered lines. Note 
that VBRMon is fully independent of the operating system. Try 
it on vour favorite take-over-the-system game! 



This is a mini-assembler for constructing small (but 
useful) routines and code patching on-the-fly. It accepts 
standard 68000 instructions in the usual (old) syntax. 



: Change or view numeric base 
Syntax: B <byte> 



This function changes the default numeric base used in 
expressions. (All commands accept expressions in addition to 
simple numbers; see the ? command description for a list of 
operators.) The input is always in decimal, which allows you to 



Figure Two 



Stack Arrangement Upon Entering 
Exception Wedge Routine 



A7 



status register before exception (WORD) 
program counter (LONG) 
vector offset (WORD) 
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back out of the otherwise catastrophic state of being in base 3 
or another useless numeric base. Base 16 is hexadecimal {the 
default), base 10 is decimal, and base 2 is binary. 



Function: Compare memory, listing differences 
Syntax: C atarti endl start2 



The compare command compares the corresponding 
bytes in two blocks of memory, listing the address of each 
different byte in the first block. Note that the addresses are not 
stored in the hunt buffer (see the L command). 



Function: Disassemble 68000 instructions 
Syntax: D <start> <end> 



Function: Enable guru trapping 
Syntax: GURD 



This function patches vectors 3, 4, 5, 10, and 11 to 
immediately invoke VBRMon without checking the mouse 
buttons. This is extremely valuable for debugging purposes. 
Guru trapping may be disabled by a second invocation of this 
function. 

Note that a different kind of guru trapping is always 
available. If you reboot (control-amiga-amiga) after receiving a 
guru meditation alert, VBRMon will automatically be invoked, 
and the register set (stored by Exec at S180) will be available 
for viewing. This is a more passive approach than the GURU 
function. 



The disassemble command disassembles standard 68000 
instructions into their mnemonic equivalent, using the usual 
(old) syntax. 



Function: Fix ExecBase and reinstall VBRMon 
Syntax: E 



This command is typically used after executing some 
program (e.g., a take-over-the-system game) that smashes 
ExecBase. It will restore the original ExecBase (saved when 
VBRMon was first invoked on the command line) and also 
reinstall VBRMon into the KickTagPtr/KickMemPtr fields. 
This can be an extremely convenient feature! 



Function: Hunt 

Syr.',:.;: H start end cbyte:> <byte> ... 



The hunt command searches a memory range for any 
and all occurrences of the specified byte string, printing the 
addresses of any matches. In addition, the first few match 
addresses are stored in the hunt buffer, which may be viewed 
using the L command. The syntax is the same as for the fill 
command. 



Function: Info about this program 
Syntax: INFO 



Displays a few programming credits for VBRMon. 



:.: Fill memory with pattern 
Syntax: F start end byte <byte> <byte> . . 



Function: Jump to address via JSR 
Syntax: J address 



The memory range indicated by the start and end 
addresses will be filled with the byte string supplied. Use 
single quotes to indicate a text string. 



- motion: Joystick autofire 
Syntax: FIRE <port> 



This function causes VBRMon to perform a JSR to some 
subroutine. The subroutine is executed within VBRMon's 
context, but the subroutine inherits (and modifies) the current 
registers (DO- D7/A0-A6) as displayed by the R command. The 
vector base register is set to before jumping to the subroutine, 
and restored afterwards if the routine returns. 



The feature is provided for your gaming amusement. Il 
provides a steady stream of "fire" by toggling the joystick/ 
mouse fire bit in the CIA, which this function configures as an 
output. It is okay to press the button while this function is 
active; no hardware damage will occur. 

The <port> parameter is the port number, either or 1. 
Invoking FIRt with no parameters turns all autofire off. 



: List hunt buffer 
Syntax: L 



When the hunt (H) or offset hunt (O) command finds a 
match, it stores the address in a 36-entry hunt buffer, which 
may be displayed with this command. This avoids the need to 
repeat lengthy searches simply because the addresses have 
scrolled off the screen. 
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.: Show memory (hex and ASCII) 
Syntax: M <start> <end> 



The M command presents a simple hex and ASCII dump 
of memory. Note that the hex part is stored in the form of the 
memory modify command (:) so that you may edit the hex 
dump bv simply moving the cursor to the byte you wish to 
modify, making the desired change, and hitting return. 



Function: Show or modify registers 
S;.T.:^x: R<reg=value> 



R by itself displays the current register set (usually the 
register set of the interrupted program) as well as INTEN AR/ 
DMACONR. The registers may also be modified, like so: 



rd0=123 
ra6=676 



Function: Toggle NTSC/PAL 
Syntax: N 



This function switches Agnus (the 1MB or 2MB variety) 
from PAL to NTSC or vice versa. Note that VBRMon remem- 
bers your selection and forces either NTSC or PAL upon a 
warm boot, so it can do the job of the many "NTSC/PAL boot" 
programs in the public domain — and quite a bit more! 



Function: Hunt for offset (PC-relative or branch) reference 
Syntax: address 

Often one wishes to search memory for a reference to a 
certain memory location (either code or data). Absolute 
references are easy to find; simply search for the destination 
address using the hunt command. However, PC (program 
counter) relative references (such as lea dest(pc),aO) and branch 
references (all of which are PC-relative) are more difficult to 
find. PC-relative references can be up to 32K away from the 
destination in either direction, so searching manually is out of 
the question. This command does it automatically, displaying 
the address of the instruction(s) that refer to the address given 
in the O command. The addresses are also stored in the hunt 
buffer (see the L command). 



The modified registers will be passed to routines 
executed with the J command. In addition, your changes will 
affect the currently running program if you use the XMOD 
command to exit. 



r _-.c^::r.: Restore register set from itemory 
Syntax: RESTORE address 

The restore command retrieves a register set previously 
saved with SAVE and makes it the current register set. 



Function: Step (find current track) 
Syntax: S drlvenunber 



The step command reports on what track (actually 
cylinder) the specified floppy drive is currently on. This is 
implemented by stepping the drive toward track zero, while 
examining the "track zero" input from the drive. The number 
of tracks stepped before reaching track zero indicates the 
current track. The state and position of the drive is restored 
afterward. Drive number ranges from to 3. 



-'■/,:• Save registers tc memory 
Syntax: SAVE address 



Function: Toggle printer output on/off 
Syntax: P 



Enabling printer output sends all screen output to the 
internal parallel port (while still displaying it on the screen as 
usual). It works fine with my inexpensive Epson LX-80 printer, 
but is certainly not guaranteed to work with all printers. This 
function is extremely useful when needed. 



The SAVE function stores the current register set (phis 
program counter and INTENAR/DMACONR) at the indicated 
memory location. The layout is as follows: 



D0-D7 


(long) 


A0-A6 


(long) 


SSP 


[long 


DSP 


(long) 


SB 


(word) 


PC 


(long) 


:'. :•'..-.= 


(word) 


■ ::: 





Altogether 78 bytes are used. The RESTORE command 
may be used to retrieve the registers. 
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Function: Transfer memory 
Syntax: start end destination 



Function: 

;\:v ::■:: 



Exit 



The transfer command moves the memory region 
indicated by start and end (inclusive) to the destination 
address. A typical use is transferring the lower 512K to fast 
memory, as in T 80000 300000. 



Function: Triple compare 

Syntax: TC atartl endl start2 start3 



This is a special compare function that is typically used 
for finding magic locations in games. It compares correspond- 
ing bytes in three memory regions. If the first two memory 
regions have the same value, but the third memory region does 
not, then the change in value from the first two to the third is 
displayed in the following convenient form: 



Third_F.egion_Mdress: XX •> YY 

An example is helpful in understanding why this is 
useful. Suppose you want to find the memory location 
containing the current number of lives in a game (Blood 
Money, let's say). The procedure is as follows. First, start the 
game and enter VBRMon, Copy the lower 512K to some free 
location. Then, do as much as possible in the game (move your 
ship around, shoot some enemies, etc.) without being killed. 
Again save the lower 512K to a free memory region. Now 
permit your ship to be destroyed. Assuming you have chosen 
to store the copies of the lower 5I2K in the first megabyte of 
autoconfig space, the appropriate triple compare command is 
as follows: 

TC 200000 2B000Q 280000 



The exit command restores the system state as much as 
possible and resumes execution. If the host application (e.g., 
game) reinitializes all the display registers in the copper list, 
the exit will be "clean." Otherwise the display will be mangled 
to varying degrees. There are two likely solutions to this 
problem (assuming you view it as problem): 

1. Take advantage of an MMU to keep track of CPU writes to 
write-only custom chip registers. I only have a 68010; 
otherwise I would have done this. 

2. Make a version of VBRMon that works over the serial port, 
much like RomWack. I may implement this in the future. 



Function: Exit with modified registers 
Syntax: XMOD 



Same as exit above, but uses the modified register set 
(including SSP, USP, SR, and PC). See the R and J command 
descriptions for additional information. 



Function: Modify memory bytes 

Syntax: : address byte <byte> <byte> ,. 



This function simply places the specified series of bytes 
at the specified memory address. Strings are supported here as 
elsewhere (use single quotes). See the 'M' command descrip- 
tion for an alternative method of modifying memorv. 



Function: Calculate 
Syntax: ? expression 



In practice you will wish to perform the compare in 
stages, so as not to be swamped with information (if this 
happens, hit the escape key to abort). If you see something like 
"00008C29:03 -> 02", you've found the magic location! 



Function: Copper unassemble 
Syntax: O <start> <end> 



This command implements a nice copper disassembler. 
Note that the disassembly process always halts when it 
encounters a CEND ($FFFF,$FFFE), a useful property. 



This command evaluates the given expression and 
displays the numeric result in hex, decimal, and binary. The 
available operators are as follows: 



+,-,*,/ - add, subtract, mult 
& - and 
- or 
* - exclusive or 
- - not 

S - hex override 
_ - decimal override 
t - binary override 
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Multiple nestings of parenthesis are supported. The 
following precedence is maintained (from high to low): 



1, Things in parenthesis 

J. •, 

3. -,- 

4. i, ,*,- 



Please note that all commands support complex expres- 
sions of this form wherever a number is required. Text strings 
may be specified using single quotes. 

Adding Your Own Commands 

It is very easy to add your own commands, and I hope 
many of you will do so. To illustrate, let's examine one of the 
simpler commands already in VBRMon, the calculator: 



Calculate 








bsr 


GetArg 




bcs.b 


.EndCalc 


: - nt hex and dec 


ira! versions 




::'.'£. 


dO,-(sp) 




-c.'.'e . '. 


'.-■": 




pea 


(CalcFtit.pc) 




bsr 


PrintLong 




1 •:■= 


(12,sp),sp 


; Print binary version 




- we . 1 


dO.dl 




moveq 


I31,d; 


.binloop: 








move.b 


tt'O'.dC 




lsl.l 


(tl.di 




bcc.b 


. skipl 




rvove.b 


i'l'.SG 


.skip!: 


bsr 


PrintChar 




■:.-■:--: 


d2, .binloop 




lea 


(KyCR,pc),aO 




bsr 


Print 


;Soak 


excess ar 


3S 




t E 1 


GetArg 




bcc.b 




.EndCalc: 


rts 




... 








dc.b 


'Hex: $%081x' ,$< 


Calcfltitl: 








dc.b 


'Dec: lid', Sa 




dc.b 


'Bin: 4%' 




dc.b 







even 





Note that this routine is not responsible for the grunt 
work of evaluating the given expression; rather, that is 
handled by the GetArg subroutine. GetArg will parse the 
command line starting with the current location and return a 
single number in DO.L indicating the final result of the 
expression. If the carry flag is set after calling GetArg, no 



argument was available (end of command line). Strings are 
automatically handled. The calling program receives each 
character of the string as a separate argument. To retrieve a 
single raw character, call GetChar or ^GetChar (the latter 
provides tor register saving and other niceties). 

Several routines are available for printing to the screen 
(and the printer if that option is enabled). Print takes a pointer 
to a simple text string in AO. PrintChar prints the character in 
DO.B. PrintLong is a Printf-like routine that accepts its argu- 
ments on the stack; see the above code excerpt for a usage 
example. 

The preferred method of data storage is to allocate space 
in the global data section, which is always (by convention) 
pointed to by A5. Simply add the appropriate label and SO 
(structure offset) directive to reserve space, then reference it in 
your code as (MyData,a5). 

Note that VBRMon was designed to be assembled with 
an assembler supporting the new Motorola syntax, such as 
Macro68. Please do not consider converting it by hand to the 
old syntax; it would just be an incredible waste of time. 

The Credits 

If 1 had had to write all of VBRMon from scratch 1 would 
not have even attempted it. Fortunately, the Amiga has 
developed a large software base from which to draw. 1 offer 
my sincere thanks to the following fine people: Dan 
Zenchelskv, for his expression evaluator, great late-night 
hacking sessions, tool development, and other contributions; 
Andreas Hommel for the mini-assembler; John Veldthuis for 
his nice copper disassembler; Dave Campbell for his nicely 
commented version of RomWack; and Swiss Cracking Associa- 
tion for the cure program. 

A Call to Hack 

1 hope you can appreciate the power VBRMon gives you 
to explore the Amiga. It has become a vital part of my pro- 
gramming and hacking toolkit. For the future, I'd like to add 
more debugging support (to further support the debugging of 
user-written games and demos), more commands, serial port 
support, MMU support, virtual 68000, etc. I can't do it alone, 
however. Take VBRMon as a starting point and then create 
your own masterpiece! ryi 

About the Author 

Dan Babcock is an electrical engineering major at 
Pennsylvania State University and an avid assembly language 
programmer. Contact him on People/Link as DANBABCOCK 
or on the Internet as d6b@ecl.psu.edu. 
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A way to automatically 
change the current 
directory based on a 
wildcard name. 



The Development of an 
AmigaDOS 2,0 Command Line 

Utility 



by Bruno Costa 



"To" provides the user a way to automatically change 
the current directory based on a wildcard name, e.g., "toanim#?" 
might change directly, from any other directory, to a directory 
named ":Projects/5culpt/Logo/Animation". A smart reader 
might be asking what reason was strong enough to make a 
programmer wait for AmigaDOS 2.0 to develop such a program. 
Elementary, my dear reader, although it was possible to write 
such a program under 1.3, it was necessary to fiddle with some 
AmigaDOS structures directly and this made things more com- 
plicated than desirable. Also, the excellent wildcard routines that 
are available under AmigaDOS 2.0 would have to be written 
under AmigaDOS 1.3, and that would make things much more 
complicated. As I examined the 2.0 include files, especially the 
pattern matching and process control routines, the idea of re- 
turning to that old project came to mind, and the result is now 
very useful but still simple enough. 

This article has three main purposes, and three corre- 
sponding audiences: to someone who simply wants to install and 
use the utility, it will explain how the utility works from the user 
point of view; to programmers in general, it will explain how the 
utility is implemented, what are the algorithms and ideas behind 
it; and, last but definitely not least, to Amiga system program- 
mers, it will explain how to use some of the new powerful features 
of AmigaDOS 2.0. 



User Perspective 

"To" is obviously a command line oriented utility - it 
should not be run from WorkBench since nothing useful will 
happen. Also, floppy disk users will not benefit from its use as 
much as hard disk users will, since this program saves more 
typing as the size of the directory trees grows — but, of course, 
nothing prevents floppy owners from using it. The program can 
be used at the same time in multiple hard disks, multiple parti- 
tions and multiple floppies. 

This program is normally used with just one argument, 
a wildcard name that will be tested against all directories on disk. 
The current directory will be changed to the first directory which 
name matches with the wildcard. Note that just the directory 
name is considered for the search, e.g., if you have a directory 
called "Utilities:Comm/VT100" just "VT100" will be used. If 
there are multiple matches of a wildcard in the table, repeatedly 
calling "To" with the same wildcard will change to each match in 
turn, cycling back to the first when they are over. As an example, 
if you have just three directories that match with the wildcard 
"t#?", named "RAMrtest", "RAM:t" and "RAM;clip/timing" 
and you type "to t#?" four times, you would change to "RAM:test" 
then to "RAM:t" then to "RAMxlip/timing" and finally back to 
"RAM:test". 
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To" works based on a table that is written to the file 
"dir.table" at the root of every disk it is used in. If this table does 
not exist or is unreadable for some reason, "To" will try to rebuild 
it. This process will take some time on big disks, but can be safely 
interrupted at any time by pressing Ctrl-C. "To" has only one 
command line option, "-b", that forces the program to build the 
director}' table for the disk from which it has been run. This option 
is tobe used after creating or deleting some directories in the disk, 
and you want the new directory structure to be correctly handled 
by "To". 

Technical Overview 

Essentially, "To" does just two things: one is to gather 
data and build a table and the other is to read that table and use 
the data. The search is implemented by consultinga pre-computed 
table to obtain maximum efficiency, since it takes a considerable 
amount of time to read all directories in a disk - even the faster 
ones. 

The table building part is based on a procedure that 
reads each directory, starting from the root, and calls itself re- 
cursively to read the sub-directories. For each directory it finds, 
this routine writes an entry in the table with just the full path 
name of this directory and some binary indexing information. 
Efficiency is the single reason for a binary table file to be used, 
instead of a simple ASCII one. In fact, if the table file was plain 
ASCII it could be built by the DOS command LIST, simply typing 
"LIST >:dir.table 1 format "<.s"<>s ALL". The problem is that the 
program is used to build the table once (or twice) but reads it 
hundreds of times, so it is a better programming practice to make 
the reading process faster, even if this implies a more complicated 
or slower writing process. 

After all directories have been read, the program writes 
at the start of the table file the number of directories that were 
found. This is done to simplify the reading process even further, 
since it allows the use of a fixed size structure (an array) instead 
of a variable size structure {a list), because even before read ing the 
table, the program will know how many entries it will have to 
store. Note that this permits us to allocate all the memory at once 
- one big chunk - instead of many small allocations, and also 
avoids the memory and time overhead of linking list nodes. 

The table reading part simply loads the table file in 
memory, and sets up two tables of the directories: one containing 
the full path name of each directory and the other containing just 
the name of each directory. The table with the names is used 
during the search, and the table with the full path names is used 
to change to a certain directory. 

When a pattern matches with multiple entries in the 
table, the behavior described above is very convenient to the user, 
permitting him to cycle between the options using the same 
arguments to the command. To implement this, the program 
must have a way to know which one is the next option to be 
selected. An environment variable could be used here to indicate 
which was the last option selected, and from the value of that 
variable the program would determine the next one. This is not a 
bad idea in itself, but in this particular case there is already a 
"variable" indicating for us the last option chosen: the current 



directory name. This string, easily obtained from the system, will 
help the program to decide which is the "next" option in the user 
point of view. This is implemented by searching first for the 
current directory in the table and, after its place is found, the 
program searches from thereon fora match with the pattern. The 
search continues in a cyclic fashion, going back to the start of the 
table when it reaches the end, until it finds a match or comes back 
to the current directory. If any match is found, "To" changes to the 
new directory. 

You should notice at this point that the table is searched 
linearly, i.e., the program sequentially tests each entry in the table 
to see if it matches the pattern — if it does not, the program tries 
the next. It should be fairly obvious that this is not an efficient 
solution, since the program will have to test many entries until it 
finds the right one (or quits searching). There are at least two 
simple, efficient and well-known algorithms to search for names 
in tables: binary search and hashing. Both of these rely on a table 
previously ordered based on a particular criteria, and then start 
searching directly ata place that is usually very near to the target. 
This place is quickly calculated based on some properties of the 
string we are trying to find, and, because of this, both of the 
algorithms are inadequate for our use. Unlike these algorithms, 
described in many computer science textbooks, we are not 
searching for an exact match of two strings of plain characters — 
we are searching for a wildcard match. This makes the task of 
calculating an approximate guess based on the search string 
completely nonsense (at least using the traditional methods for 
the two algorithms mentioned), and binds us irremediably to the 
linear search. Since our main concern is execution speed, if the 
linear search is "fast enough" we won't have any reason to 
complain. Casual tests ha ve shown that it has a good performance 
indeed: even with almost three hundred directories in a hard 
disk, "to" executes in a (sometimes lethargic) blink of the eyes, 
indistinguishable from the time taken to execute "CD", for instance 
("CD" is obviously much faster, but the difference is not really 
noticeable to a human being). 

AmigaDOS 2.0 Usage 

Most of the code described up to now is relatively 
independent of AmigaDOS. If fact, the same ideas can be suc- 
cessfully used to implement a similar u tili ty un der other opera ting 
systems, such as MS-DOS and UNIX, if the system dependent 
functions are provided, 

Some features of previous versions of AmigaDOS were 
used where there was no need for new functions. Some of the file 
managing routines, such as Open( ), Close( ), Read( ), Write( ), 
Lock( ), UnLock( ) and Seek( ) were used to handle the table file. 
IoErr( ) was used to handle AmigaDOS errors, Examine( ) and 
ExNext( ) were used to read directories and CurrentDir( ) was 
used to change the current directory. To better understand the 
usage of these functions, please refer to "AmigaDOS for Pro- 
grammers" (AC's TECH premiere issue). 

Twofeaturesof AmigaDOS 2.0 werespecially important: 
the SetCurrentDirName( ) function and the pattern matching 
functions ParsePattern( ) and MatchPattern( ). 
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The SetCLirrentDinMame(name) function is used after 
you use CurrentDir( ) to change the directory, since the latter 
function does not change the directory name in the process 
control structure - just the current directoiy itself (odd, isn't it?). 
Previously, to achieve the same effect, you would have to change 
a field in the process structure by hand, and this involved freeing 
a memory area and allocating a new one using some memory 
managing conventions internal to AmigaDOS. Also, the current 
directory name is stored in the process structure as a BCPL string, 
which is not really practical to C programmers. There is also its 
counterpart function, GetCurrentDirName(buffer,length) that 
fills the string buffer with up to length characters of the current 
director}' name. The addition of these two functions was very 
convenient to the development of "To". 

The pattern matching facilities of AmigaDOS 2.0 are a 
key feature to make this program possible. Although the ARP 
(AmigaDOS Resource Project) library provided almost the same 
functionality as AmigaDOS patterns, there was at least one minor 
bug related to patterns, and ARP was not in such a wide use to 
assure that even one would be able to use programs de\ doped 
for it (1 should point out that ARP was a remarkable effort, 
apparently with substantial influence in the development of 
AmigaDOS 2.0). There are two basic steps to use patterns under 
AmigaDOS 2.0: "compile" an ASCII pattern string into a more 
efficient representation, and test a pattern representation against 
an arbitrary string for a match. The former step is accomplished 
by ParsePatternfpattern, buffer, size), where pattern is simply a 
string that mav include all wildcard constructions supported by 
AmigaDOS 2.0: 



c matches with character c 

(chars) matches with any character inside the brackets 

(Achars) matches with any character not inside the 

brackets 
(str 1 1 str2 1 . . . ) mate hes with any of the strings str 1 ,str2 ... . 
#p matches with zero or more instances of p 

-p matches with anything that does not match 

with p 
? matches with any single character 

matches with zero or more characters of 

any kind (see the "WildStar" article. 

elsewhere in this issue of AC's TECH) 



ParsePattern( ) fills the buffer (up to size bytes) with a 
compiled representation of the pattern, and returns TRUE if the 
string effectively contained wildcard characters. If it returns 
FALSE it means that you can safely use strcmp( ) or similar 
routines instead of MatchPatternf ), although the latter will still 
v ork. The length of the compiled representation is usually less 
than tin 1 original pattern, so vou can safely use. 1 , buffer with the 
same size as the pattern string. If the buffer is smaller than 
needed, the routine will return -I. 

To test a compiled pattern against an arbitrary string use 
theMatchPattern(pattern, string) call, that will return TRUE if the 
compiled pattern matches the given string under the rules de- 
scribed above. Note that this is what is called an "anchored" 



match: each character of the string must match to a part of the 
pattern. This kind of pattern matching is very convenient to file 
names, but "free" matches are also useful in the context of text 
editors or text search utilities like the AmigaDOS search com- 
mand. In this case, if any subset of the line matches the pattern, the 
whole line matches the pattern. This behavior can be simulated, 
with a tolerable performance, by calling MatchPatternf ) sequen- 
tially for each substring of the line, as in the following piece of 
code: 



{ 



int FreeMatch iubyte 'pattern, char *line) 

Int i; 

for (i = 0; i < strlen (line); i++) 
if (MatchPattern (pattern, ilineli])) 
return TRUE; 

return FALSE; 



It should be mentioned that there is a different set of 
pattern matching functions specifically designed for wildcard 
filename expansion (as in dir *.c), which should be used for that 
case. The MatchRrst( ), MatchNextf ) and MatchEnd( ) functions 
automatically compile a pattern, read all the required directories 
and return the proper path names of the matching files, if any. 
However, a complete description of their usage is out of the scope 
of this text. 

AmigaDOS provided a simple but efficient set of file 
handling functions, basically formed by Open( ), Close( ), Read( 
) and Write( ). These routines implemented what is called un- 
buffered files, i.e., each time Read( ) or Write( ) is called the 
physical device is accessed to get the information. When using 
buffered files, however, the information to be exchanged with the 
physical device is kept in a buffer managed by the system. This 
kind of I/O is mostly useful when the file is accessed in multiple 
small reads or writes. After multiple write operations, for instance, 
only after the buffer becomes full a real write access to the 
physical device will occur, writing all the information in a single 
big operation. Although buffered files are almost a must in these 
cases, the addition of this capability to AmigaDOS 2.0 will not be 
easity noticeable to most C programmers: the standard C I/O 
library provides this functionality (using fopen( ), fclose( ), fwrite( 
), fprintf( ), fputc( ), fread( ) and so on) in a portable fashion, very 
easily implemented in the Amiga using Read( ), Write( ) and a bit 
of C code. 

"To" uses some of these new buffered file handling 
functions, that are completely analogous to their standard I/O 
library lowercase counterparts. Most of these should be clearly 
described in your C compiler manuals or any C reference book, 
but some AmigaDOS details should be explained. The buffered 
files are opened exactly the same way as the unbuffered files 
were; using Open( ) and CIose( ). To indicate that a particular file 
is to be buffered, you simply call SetVBuf (f ile, bufmode, bufsize). 
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The size in bytes of the buffer to be used (allocated internally by 
AmigaDOS) is given by bufsize, and bufmode is used to indicate 
which buffering mode is to be used: either BUF_FULL,BUF_LINE 
or BUF_NONE. BUF^FULL indicates that the buffer should be 
flushed only when it is absolutely necessary, BUFJJNE forces 
[he buffer to be flushed whenever an end-of-line {* ,n")is found 
and BUF_NONE disables any kind of buffering. 

As in the buffered file case, this new version of Amiga- 
DOS also tried to offer to the programmer some more useful 
functions that had to be implemented over other basic primitives 
of the operating system. Some of them, especially the file name 
manipulation functions, have been used in "To". FilePart 
(fullpathname) returns a pointer to the file name part of 
fullpathname excluding the path, e.g., FifePart ("ram:t/test") 
returns "test". AddPart (fullname, objname, fullnamesize) con- 
catenates objname (usually a directory or file name) to fullname 
(usually a pathname) adding a slash between them if needed. The 
resulting path name will use at most fullnamesize characters of 
fullname. 

Anotheruseful addition is the function NameFromLock 
(lock, lockiiame, namestze). It returns in the string lockname at 
most namesize characters of the full path name (including volume 
name and all directories) of the file or directory given by lock. As 
you should know, a lock is a handy unique identification for a file 
or directory, and it ensures that this particular object will be valid 
while you have it locked. Also, if the user renames a file, all locks 
to it remain valid, since they are independent of the file effective 
name. NameFromLock( ) may be seen as the inverse of Lock( ): 
Lock( ) returns a lock when given a file name, and NameFromLock( 
) returns a file name when given a lock. Please note that this 
mapping is not necessarily one-to-one, since there are many path 
names by which a particular file may be referenced (using relative 
paths, assigned names and so on). To better understand 
NameFromLoek() you might wish to examine an implementation 
of a similar function, given in "AmigaDOS for Programmers" 
with the name fullpath( ). 

A new call has been provided in Amiga DOS 2.0 to check 
for a break request (either typing Ctrl-C, D, E or F, or issuing the 
shell command BREAK): CheckSignal (sigmask). It is essentially 
calls the exec function SetSignalf ) and checks if one of the signals 
in sigmask has been received; it was added just to convenience the 
AmigaDOS programmer. In the samesense, ExamineFH (file, fib) 
is exactly like Examine( ) but instead of giving the file by a lock, 
it is given by a file handle. 

What if I don't have Workbench 2.0? 

This is a very important question. It seems that the 
upgrade to Workbench 2.0 is not a trivial task to most Amiga 
owners, and some of them may prefer to postpone this upgrade 
to a later date. Specially in this conversion phase it becomes very 
important to try to support both systems, but since Workbench 
2.0 is much more powerful, it will be probably difficult, most 
often impossible, to do so. If you run a program carelessly 
designed for Workbench 2.0 systems under 1.3, it will usually 
crash the machine immediately. Also, if you want to support both 
systems, it will be important to detect when Workbench 2.0 is 
available to be able to safely use its features. So it is now absolutely 



necessary to check the correct versions of the libraries required. 
This is done in "To" by the the pair of functions DOSopen2_0( ) 
and DOScIose2_0( ). You should not underrate this warning, 
since this time, unlike the previous upgrades, the older version 
was not made obsolete — both are active and in use. 

A Digression on File System Links 

AmigaDOS 2.0 brings to the Amiga the concept of file 
system links, already known by UNIX users. Simply put, a link is 
a way to have two or more files, each with its own name, path and 
some attributes, referring to just one set of data. This means that 
just one copy of the file will be taking up space on disk, but to most 
(if not all) programs it will seem that each link is effectively a 
different file. Conceptually, there are two types of link: soft and 
hard. Hard links are usually indistinguishable from regular files, 
since thevare built by making two file header blocks on disk point 
to the same set of data blocks. This construction is not possible if 
the files are in different file systems (different partitions of a hard 
disk or different devices). Soft links are simply a named reference 
to another file: a special file header block says something like "if 
this file is referenced by any means, use DH0:dir/file instead" 
(they are somewhat similar to a non-binding assign, as the PATH 
option of the 2.0 ASSIGN command). Note that the file is refer- 
enced by its path name, so files may be linked across devices and, 
in fact, the target file might not even exist. Both kinds of link are 
supposed to be implemented in AmigaDOS 2.0, but as the 
documentation warns, "soft links are not fully supported yet". 

Sample Use of Links 

"To" uses links just for tutorial purposes — they were 
neither necessary, nor even specially useful, in this simple ap- 
plication. Generally speaking, links can be used to create aliases 
for files. For example, a link can be used to create an alias for a 
command, as the ALIAS command does: 

makelink C:Is C:liat 
alias Is List 

The lines above produce essentially the same result, 
al though usingcompletely dissimilar techniques. In lhi> particular 
case, the ALIAS solution should be used, since it is much more 
efficient and does not use any space on disk. There are situations, 
however, when ALIAS cannot be used and MAKELINK can: to 
create aliases for data files. If, for instance, a certain program 
requires a data file to be present in the current directory, instead 
of copying that file to every director}- where you ran that program 
from, you could make links to a single copy of the data. 

Links have been used in UNIX systems in both ways, 
even as command aliases, and there is a good reason for that. The 
ALIAS command is a feature of the shell, and it converts the alias 
name to the real program name before executing it — the program 
will never know that it was called by its alias. With I inks however, 
using the standard C startup, argv|0] will contain the name by 
which the program was called. This is useful if the program wants 
to assume a slightly different behavior when it is called by 
different aliases, effectively appearing to be distinct programs. 
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As an example, both the DIR and LIST commands could be links 
to the same executable, since both do the same thing (read 
directories) but print their results in a somewhat different format 
and support different options. 

Since "To" has two distinct behaviors (building a table 
and using it), it is a valid candidate to use this command alias 
feature: if it is called by the name "mktotbl" (for "make the To 
table") it will behave as the tabic builder. To check which was the 
name by which it was called (either "To" or "mktotbl") it uses the 
AmigaDOS 2.0 GetProgramName (progname, namesize) call, 
that fills the string progname with at most namesize characters of 
the program name. It would be obviously possible to use argv[0] 
instead (in fact the startup code uses something similar to 
GetProgramNamet ) to fill argv[0]). Note that in this particular 
case, the following line would have approximately the same 
effect as the link: 

alias mktotbl "to -b" 

As 1 mentioned before, this feature was added just as an 
instructive experience. 

Source Code Guide 

Apart from the error handling details, "To" will load the 
table, search for the current directory in the table, search from 
thereon for a pattern match and if a match is found, change to the 
new directory. It the program was invoked with the "- b" option 
or by the "mktotbl" name, it will instead build the table. 

The table construction is implemented by scandir( ), a 
recursive function that reads the contents of a given directory, 
adds each sub-directory to the table using addtotable( ) and calls 
itself recursively - non-directory entries are ignored. 

The table saving process is composed by opentable( ), 
closetable( ) and addtotable( ): opentable( ) opens the file and 
writes the header; closetable( ) writes the directory count and 
close the file; addtotable( ) writes the given directory to the file 
and increments thedirectory count. These three functionsand the 
scnndir( ) function are called through the front end buildtable( ), 
that implements the proper calling sequence and parameters to 
effectively build the table. 

Most of the reading table procedure is contained in 
loadtable( ). This function will try to open the table file, call 
readheader( ) to read the header and alloctables( ) to allocate 
memory for the tables with the size specified in the header. The 
table itself is read and stored in filebuf by a single Read( ) — if 
some kind of error occurs, loadtable( I willcall freetablesl ] to tree 
the memory. After that, two indexes for the table are built in 
memory, in such a way that there is an entry in each of them for 
each directory in the table: nametbl|n] points to the name and 
pathtbljnj points to the full path name of the nth directory. 

There are also the support functions, each one relatively 
simple and self-contained: fullname( ), used to get the full path 
name of a directory given by its name and a parent directory lock; 
cd( ),thatchanges the current directory toanother directory given 
by name; and filesize( ), that returns the size in bytes of an opened 
file. 



Examine the source code in the listing below carefully, 
as it is fully commented and explains some details that con Id not 
be mentioned here. You are also encouraged to modify it as you 
wish — as long as you do not redistribute the modified program 
— and use parts of the code anywhere you want. It should be 
mentioned that this small utilitv has been in use for a significant 
amount of time, and it is most unlikely that any serious problems 
may arise. Anyway, besides being a useful program, I hope that 
"To" will serve as an enjoyable learning tool. 




to.c - changes to aaiy directory rased on pre-cosputed directory tree 

fcsta - 30 Jan 91 - 18 Feb 91 

(Requires AmigaDOS 2.0) 
/ 

t include <exec/types . h> 
• include cdos/stdio.h> 
luiclude <clibydo3_protos. 

(include <pragjas/dos.jjragmas.h> 
tinclude <ciib/exec_protos .h> 
linclude <pragm3s/exec_prag]nas.h> 

tinclude <ctype.h> 

tinclude > 

■ 



idef ine KAfflAME 100 
tdef ine MA>:?.;: l. 



/' naximun size of full path name '/ 
■ maxims size of a parsed pattern *,' 



■■: r ::_■. ' .i_..:'y 'SysBase; ' exec. library base*/ 
struct Library 'DDSSase,- '* cos. library 1 



char fullprognamelKMOWffil ; 
char "prognose; 

:::■•: 'filebuf = NULL; 
... -■■:,._-_-_ . 

char "pathtbl =NULL; 
long tblsize = 0; 

BPlStabli file; 



/' (path) name of the program being run V 
/* name of the program being run '/ 

■' buffer where table file data is stored ' 
'■ ;i:= :- bytes of the sieve ziiii: ' 

• array of strings with directory nanes • 
'an iy of strings with full path nases */ 
/* size of the above arrays */ 

/" handle to write to the table file */ 



(define USMJBG ' -'...■..: xa9 1991 u restaur/ \ 

■usage: \xlbflaito\xlb[0ii i-b I <pattern>i \n' 

(define H-L?J- 

* Changes to a directory which Batches <patterm. Note that <pattems\n* \ 
•may not include a path specification. The sear;.-, is based on ain" \ 
_:s.: directory table that is saved to ':dir. table'. If thisVn* \ 
i:e= .-." .exist . it will be a :t illy created; otherwise the\n* \ 
'program will be instantly executed. Using the option -b will force 
'the reconstruction of the table fcr the current drive. \n" 



.1 the file that contains the table. For each volume (disk, 
ton, etc. I where TO will be used this file mist be present, and 

* will contain a listing of all the directories present in that volume. 
' 

(define TABLE_NAME ":dir. table' 

• Tabie file header def nitia [LS_ID is a saa] I I esent ... 

iding confusions - it is a hint that 
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* we are reading a file in the expected format. ID_SIZE is the size in 
' bytes of this ID string. HEADER_SIZE is the size of the header, which 

* contains the file ID and a long iat representing jf 

* directories listed ir. this file. 



(define PILBJB'DIRT" 

Idefine ID.SIZE Isizeof (FILEJDI - II 
•define KEADER_5I2E ■ [D_SIZE i sijeof tbl 



/' discounts '\0' 



♦define SQ3ROGG "Sorry, you must upgrade to " \ 

'Workbench 2.0 to run this program. \n" 



■ 



* Mattes fay which this program is expected to be ran. Sased on the name 
•by which the user calls the progra-, it will behave differently. This 
' .. leant to be used in the following way: the executable is copied to 
' your C: directory with the name CHANGER,- then you nake a soft link 

* uaned EUILDER to it; then ycu nay call either command by the. correct 

* r.sre ar.d the same code will be invoked, but behaving apropriately. Bote 
■ that only ~~- _ :"y ' th file will he taking .: space :r ::.:-.. 

•■' 

♦define BUILDER "nktotbl' 
♦define CUMBER 'to' 



* Returns MK if the FileIr.::IL:r: -:::-::.:re pointed to 

* by fib refers to a directory. 
'/ 

•define isdirlfib) (fib->tib_DirEntryType > 0) 

/• 

* A new C language . . ructare . . . 

(define loot fori;: 

/' 

* Returns TH'JE if two given strings are the sane Icase-insensitivel . 
■ 

♦define strsane!strl,str2l lstr:-rc latrl, strtl ==0) 



I* 



* sunetkws ne'f ~ 1 :.. 



/■ miscellaneous ■ 

: :har "fullname IBPTRdirlcck, unsigned char v.ar.e; ; 
unsigned char 'cd (unsigned char *cirl; 
iong filesize (BPTRfilel; 
void strlower [unsigned char 'str) ; 

/• table ::: 

void] ; 
voidclosetable ivoidl; 
int addtocable (unsigned char "pathl ,- 
int scandir (unsigned char 'dimamel ; 
int buildtable ivoidl ,- 

. ' table reading */ 
int readheader [3PTR file); 
int alloctables Ivoidl; 
void freetables (void); 
int loadtable (voidl ,- 

/* Error handling '/ 

void DOSopen2_0 Ivoidl; 

void DOScloseZJ Ivoidl ; 

void puterr (unsigned char "msg); 

void fail lunsigned char *sag) ; 



• This program bases .ly three -ain parts. The first is a table 
' writer: it scans all directories in a particular drive or partition and 

• saves all directory names to a table file in that drive. The second is 
■ a table reader: it reads the table file produced by the first part and 

• stores a representation of it in memory. The third is Che table 

• scanner, that simply consults the table in aenory to find a directory 

• that -atch.es a .set specified pattern and changes to if. The first and 

• second parrs are below maind , in apropriately labeled sections, and the 

• third is inside Bain itself. 



void main (int argc, char "argv|]l 



I 

DQSopen2_fi 1 1 ; 

GetProgranSaie (fullprogname, KMOOHE) j 
prognane = FileFart (fullprogna 

i! (strsame (pregnane, BUILDER)) 
I 
if (Ibuildtable (II 
fail I'cauld not build table. \n'l; 
I 

else 
I 

: 1- != 21 

( 

PutStr IBSU5EJ1SGI ; 

PutStr IHELPJ!SGI; 
) 
else 

I 

isame (*-b", argvUlll 
[ 
if I Ibuildtable (I) 
fail ('could not build table. \n" 
) 
else 



/ " ignore path ' / 

/■ behave as BUILDER */ 



/• behave as :-r 
/" if incorrect ♦ of args, prints help 'I 

• . rrg, i: the trie''; • 



I 

in: found; 

char "*p, "n, *'q, "cdptr; 
char pat [KAXPAT1; 
h : itaneiHAXMAHI i 

if (lloadtabie III 
( 

if [Jhuildtabla (II 
fail 'could not build table. \n*li 

if ((loadtable [|] 
fail ('table file is corrupt ! \n' I ; 



GetCurreotDirMaae [canaais, KAXNAHE] ; 



If we are at the root directory, we know that it is not in the 
' table - we don't need to search. Otherwise, search for the 
current director!' in the pathnames table. 
V 



f--j:.d = rALJc; 

if (cdna.tels:rlen(cdname) - 11 



/* are we at the root ? '/ 



fir :.-. = nanetbl, p = pathtbi, q = n • tblsize; n < q; »♦♦, p-- 
if istrsane ("p, cdnacel I 

1 
found = TS"JH; 
cdptr = n; 

break; 

) 

if (1 found 
puterr ("current directory is not in tab] 

) 

if (Ifoundl 

I 
n = nanetbl; /* if the current director/ is not in the ' 
p = pathtbl; ■ labie, set up things so that the search ■ 
I=st tblsitej ■ starts from the beginning of the table. */ 
cdptr = n: 

! 



• Prepare a case-insensitive search Isince table is ail losercase) 

strlower (arg-.\; 

ParsePattem (argv[l), pat. IftXPAT); 



* Searches for a directory name that aatthes the pattern, starting 

* froo the next place after the current directory. If there : 

f pattern in the table, this assures 

* that the user will be able to cv:le among then just by repeating 

■ the sape cc—ar.d. ::;:■; that we jse the table in a cyclic fashion. 

* going back to the start if we reach the end of it - the search 

' only stops after we ccsie back to the current dir after finding no 

■ other match. 
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found = FALSE; 
do 

I 

• •n, -.p; /' these pointers always go along *t 

if In >= a) /* close the circle */ 
{ 

II : BaMtM; 

p = oathtbi; 
J 

if (KatchFattem (pat, 'nil 
1 
found = TRUE; 

break; 

) 

} while [n != cdptrl; 

if (! found! 
fail ("no directory matches\n'l; 

if lied I'pii 

fail ('could not change directory\n'] ; 



DOScioseZJ (I; 
exit (RSTURNJK); 



The table is saved in the following format: 
name size(bytes) contents 





FilelD 


4 




Ndirs 


I 


s -- 






r. 


iathLer. 


1 


t 


path 




: 


Er.d?a:h 


1 


1 *- 







_,-..'- 



'DIET' - identifies table file 
number of entries that follows 

si 26 of Che following string 

FULL path nane of a directory 
- terminates the path string 



' Opens and prepares the table tile for writing. Returns FKOK if 
• successful. 

•I 

ir.t opentable (void) 
! 
tablefile = Open (TA3LEJIAME, MODEJIEWFILEI ; 

if Utabiefile) 
return FALSE; 

/* 

■ Use fully buffered I/O to minimize file manipulation overhead. 
'/ 

SetVBuf (tablefile, BUF_FULL, 40001; 

tblsize = 0; 

/' 
* Write a header to identify the ftle, followed by the total number ol 

■ directory entries that follows. Sate chat at this time this number is 
' nat yet known, so we -write a to reserve space for it, and patch it 
" with the corrected value later. 

*/ 

FKrite [tablefile, riLE.lD, id.size. 1); 
FWrite (tablefile. itblsize, sizeof (tblsizel, 11; 

return TRUE; 



* Finishes the writing of the table file, 
void closetable (void) 



( 

if Itblsize == 0! /' an erpty table does not make any sense '/ 
I 

Close | tablefile); 

DeleteFile (TABLEJffllGI ; 

puterr ("no directories found!\n'); 
) 

else 
I 

' Write buffers to disk, to ensure a correct SeekC operation. 
*/ 
Flush (tablef ilel ; 



" Rewind to a place near the start of the file, where we reserved 

* space tor the count of directory entries, and patch it with the now 

• know value. 
*/ 

if (Seek (tablefile, IDJIZE, OFFSCTBEGHNINGI == -II 

puterr ('seek errorI\n"); 
else 

FWrite (tablefile, stblsize, sizeof (tblsize), II; 

Close (tablefile); 
I 



' Add a particular directory, given by its full path name, to the 

' currently open table file. Returns TRUE if successful. 

'/ 

int addtotable (char 'path I 
[ 

int pathlen = strlen (path) + I; 

strlower (path); /• table is all lowercase to be case insensitive '/ 

/* 

" Write a string containing the full path name of a particular 
' directory, including a terminating ' 10' and preceded by a byte with its 
* length. 
•/ 
FPutC (tablefile, pathlen); 
FWrite Itablefile, path, pathieh, I); 

**tblsize; 

if iCheckSignal (SIGBREAKF_CTEL_CI 1 /* check for "C abort V 

return FALS£; 
else 

return TRUE; 
! 



' Recursive function to read directories . For each directory given by 

* its full path name, it reads the contents of :t adding each of the 
' directories inside it to the currently opened table file and calling 

* itself recursively. Returns TRUE if successful. 
'I 

int scandir (char 'dirname) 
( 

int success = FALSE; 
BPTR lock; 
struct FilelnfoElock *info = malloc (sizeof ('info) I ; 

if (Jinfo) 

puterr ("out of neH!\n'); 
else 
■ 

lock = Lock (dirname, SKARED_LOCKI ; 
if Clock) 

puterr ('could not lock directory !\n'l; 
else 
i 
if I ; Examine dock, info)) 

puterr I'cpuid net examine directory! \n'); 
else if lisdir (infol) 
{ 

loop 
! 

if OExHext (lock, info) I 

::-;-■:; /* if error, stop reading •/ 

else if (isdir (info)) 
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UPDATE 



Some readers have shown some concern about 
the unlharc'ing of the files on the AC's TECH disks. It 
seem that they get confused with the operation of 
lharc — especially if they are new to programming the 
Amiga. 

Paul Castonguay has taken the initiative to write 
an extract program which will allow lharc file to be 
extracted from the WorkBench. We have implemented 
Extract starting with this diskette! 

To extract an lharc file from the workbench: 

Lharc files tvill have a 'lock' icon — 
Double-click the icon, which zvill run the 
Extract application. 



A window -will appear, asking you for a destination path. 

Type your destination path (e.g. RAM: or dhO:) and a new 
drawer with the contents of the archive, will be created in the 
destination path. 

Many thanks to Paul Castonguay for this fine addition to 
the AC's TECH Disk! 

If you have any suggestion for AC's TECH, please send 
them to: 

AC's TECH Suggestions 

P.O. Box 869 

Fall River, MA 02722-0869 



WE INTERRUPT THIS HIGHLY INFORMATIVE ARTICLE 
FOR A VERY SPECIAL PROGRAM ANNOUNCEMENT! 

We want to publish your very special program in an upcoming issue of AC. 

Or, your highly informative article on any topic of interest to Amiga users of all skill levels! 

The fact is, Amazing Computing has always published the most unique, most detailed Amiga 
programming articles and tutorials found anywhere! AC pays competitive per-page rates to 
its authors, but publishes more and longer programming articles per issue than any other 
Amiea monthly. That's great news not only for our readers, but also for those of you who 
are thinking about achieving fame and fortune as freelance writers! And now, the more 
complex works of high-level programmers are considered for publication in AC's TECH. 
The fact is, AC's TECH is the #1 all-technical, disk-based Amiga journal. 

Whatever your areas of greatest interest or proficiency on the Amiga, there are probably any 
number of tips, techniques and tricks you can communicate to Amiga users worldwide, in 
the pages of Amazing Computing. 

Even if you have never been published before, you should consider writing for AC. Our 

knowledgeable, experienced editors are the most helpful in the business. 

Call our editorial offices during normal business hours at 1-800-345-3360 to have 
the Amazing Computing Author's Guide information packet sent to you TODAY! 
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ACs TECH Disk 

Volume i, Number 3 



A few notes before you dive into the disk! 



• You need a working knowledge of the AmigaDOS CLI as most of the files on the 
AG's TECH disk are only accessible from the CLI. 

• In order to fit as much information as possible on the ACs TECH Disk, we archived 
many of the files, using the freely redistributable archive utility 'lharc' (which is 
provided in the C: directory), lharc archive files have the filename extension .Izh. 

To unarchive a fik foo.lzh. type lharc xfoo 

For help with lharc, type lharc ? 

{see UPDATES for more information about unarchiving) 




We pride ourselves in the quaiify of our print 
and magnetic media publications However 
the highly unlikely event or a faulty or darn- 
aged disk, please return the disk to PiM 
Publications, Inc. fci a u&e iwpiocernent, 
Please return the disk to: 

ACS TECH . 

Disk Replacement -„ 

P.O. Box 869 
Fall River. MA 02720-0869 



n 



Be Sure to 
Make a 
Backup! 



CAUTION! 



Due to the technical and experimental nature of some of 
the program* on the ACs TECH Disk, we advise the 
Euderio use caution . especial ly when using experimental 
programs thai irvilialc low-level disk, access. The entire 
L.Lhiliiytjf the quality ;tnd performance of the software on 
the ACs TECH Disk is assumed by the purchaser. PiM 
Publications. Inc. their distributor, or their retailers, will 
not be liable for any direct, indirect, or consequential 
damages resulting from ihc use or misuse of the software 
nnlhe ACsTECH Ui ^k. (This agreement m;iy run apply 
in Jill geographical areas} 



Although many of the individual files and directories on 
ihc ACs TECH Disk are freely redistributable, ihe ACs 
El-CHDiskiuelfandihecoiIeciiermf individual files and 
directories on the ACsTECH Disk are copy right fi]990, 
1991 by PiM Publications. Inc. and may not be duplicated 
i ii .my \\ ;i\ The purchaser however is encouraged (0 make 
an archive/backup copy of the ACs TECH Disk. 

Also, be extremely careful when working with hardware 
project*. Check sour work, twice, to avoid any damage 
that can happen, Also, be aware that using these projects 
may void the warranties of your computer equipment. 
PiM Publications, or any of it's agents, is not responsible 
for any damages incurred while attempting this project. 
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( 

char "nane = fuiliBBe (lock, info->fii_F::ef;ize; ; 

if Kaddtotable Inane] } 
break; 

if ( (scandir (name) ) 
break; /* if error, scop reading '/ 



if UoErr [) ^ £?;::-j;:j::?E_i~:;£) /' if terminated noraaliy '/ 

success = TRUE; 
) 

UnLock (lock); 
) 
free (info]; 



return success; 



/• 

♦ Builds Che directory table for the drive where this coroand was 
•executed from. Calls scandir 1 1 to do the real work. Returns TRUE if 

• successful - 
*/ 

inc buildtable (void) 

( 

int success, - 

puterr ("building table - please wait .. An') ; 

if (success = opeotabla 
I 

success = scandir (■:■); 

closetable (I; 
I 

return success; 



/* Table Reading "/ 

/' 

* Reads the header of a table file, storing the useful information in 

• the proper places. It also checks if the file is in a suitable format, 
■ Returns TRUE if successful, 

V 

int readheader (BPT3 file] 
I 

char id[ID_SIZE* lb 

bufsize •= filesize (file) - HEAD£R_SIZE; 
if Ibufsize > 0) 
if Head (file, id, ID SIZE] == ID_5IZEI 
{ 
id[ID.SIZE] = '\0'; 
if (strcmp lid, FILE_ID) == D] 
if (Read (file, itblsiie, sizeof Itblsizell == sizeof (tblsize! I 
if Itblsize > 5) 
return TRUE; 
) 

return FALSE; 



• Allocates the tables and the buffer used to hold the table file in 

* eenory. Returns TRUE if successful. 
•/ 

int alloctables (void) 
I 

filebuf = salloc (bufsizel; 

nametbl * calloc Itblsize * 1, sizeof (char *l ] ; 

pachtbl = calloc (tblsize » 1, sizeof (char '! ] ; 

.: :..ebuf ii nasetbl SS pachtbl I /* if allocation succeeded */ 
return (TRUE); 

freetables I); 
return (FALSE); 



* Trees the tables and the buffer used to hold in Bserory the information 

* present in the table file. 
•/ 

void freetables [void) 

I 

if Ifilebufl 

free (filebuf]; 
if (nasetbl! 

free [nanetl 
i! [pachtbl] 
free (pathtbl); 



/' 

* Loads a table file in memory. 
*/ 

int loadtable Ivoidl 
{ 

BPTR f = Open (TABLEJiAME, WOQEJLDFILE) ; 
if |!£| 

puterr ("could not open table fiie\n"); 
else 
I 
if I (readheader If)) 
puterr ("table is corrupt !\n'); 

~.S-.' 
( 

if (lalloctables 0) 

puterr ("out of Bem!\n"l; 
else 
I 

if (Read If, filebuf, bufsizel != bufsize) 
puterr I'error reading uble\n']; 
else 
! 

int i = 0; 
char "p = filebuf, *q = p • bufsize; 

" 

• Set up the arrays of directory nazes and path oases tc point 

* to the proper places in the file buffer, which contains 
' essentially a copy of Che file contents. 

"/ 
while (p < q it i <= tblsize) 
I 

pathtbl |U sp ♦ 1; 

nanetbl[i] = FilePart (p * 1); 

p *= *p + 1; 

t»i( 
) 



f* if the loop terminated normally */ 
/* if successful, return here */ 



if IP ---- ql 


Close (f); 


return BHJE 
) 


1 

freetables (1; 
} 


) 

Close If); 


return FALSE,- 



Miscellaneous 



* Returns a pointer to a static buffer (overwritten by each call) 
" containing the full path name of file with a given r.ar.e relative to a 

* given lock. 
•1 

char 'fullnaas IBPTR clirlock. char "name) 

I 

static char fullna*e[HA)OW.E] ; 

HameFreslock Idirlock, fullname, y.ABJAME) ; 

AddPart Ifullnaite, name, MMOJAKEI; 

return fu: inane; 
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changes the current directory to the one given by its path nane. 

1 Updates the proper Process stricture fields and return! the Cull path 

* name of the director/. 

■/ 

char "cd (char *dirl 
I 

BPTH newdir, old 

static char r.amebuf ;HAXNJUE] ; 

newdir = Loci; [dir, SEKHLUXK! ; 
if (Inevdir) 

return NULL; 
else 

olddir = CurrentDir [nevdii 
if (olddir] 

UnLoc's iold-iin ; 
NanerToaLoc* (newdir, nanebu:, :l\:::::;:: ; 
SetCurrer.tD.rliame (r.sEebuil ; 
: 

! 



/' 

* Returns the size :- aytes of a file given by a handle, 

'/ 

long filesize (BETR file) 
I 

long size = -1; 

struct FilelnfoBlock *f ib = raalloc Isizeof (*fibll; 

if (fib) 
I 
if lExamineFr! (file, fibll 
size = Eib-jfihSUe; 



free (fib); 



i 



* Converts all uppercase characters in a string to lowercase. 
'/ 
void strlcwer [char 'str! 



for ( ; 'str; str++l 
if (isupper Cstrll 
'str = colower I'strl; 
I 



T Error Handling ' 

/• 

* Writes an error message, preceded by the program name. 

'/ 
void puterr (char f rasg) 
1 

PutStr Iprognaae); 

PutStr (•: ■); 

PutStr Imsg); 
) 



* Writes an error message, and then exits with a failure code, 

•/ 

void fail (char 'asg) 
( 

puterr irsgj ; 

D0Sc!ose2_0 ( I ; 

exit (BETOBK_FAIL); 
( 



* The two functions below are used to assure that JaigaDOS 2.0 is 
•present which is required for this program to work. If it isn't, the 

* code below tries to open the previous version of the library (1.3) just 
' to print a message, and exits. 

'/ 
voidDOSopen? (void) 
I 

DOSBase = Openiibrary I *dos. library', 361; /* requires 2.0 "/ 
if (DOSBase == SOLLI 
( 



DOSBase - OpenLibrar/ Coos. library, 33) ; 
if (DOSBase) 
1 

Write (Output I), SOSSYJISG, sizeof (SORRY.KSG)); 
CloseLibrary (DOSBase) ; 
1 
exit (aETUKKJ'AIL) ; 



/* try opening 1.3 */ 



) 



void DOSclose2J Ivoid) 
I 

if I DOSBase I 
CloseLibrary (DOSBase) ; 
) 



IT] 



Confused with programming or accessing basic 
AmigaDOS functions from C? 



)? 



Z 4- ^ / 



Read AmigaDOS for Programmers, by Bruno Costa 
in AC's TECH Premiere Issue. 

AC's TECH Back Issues are just $14.95 each 
O C k For Back Issues > caU l -800-345-3360 

(credit card orders only, please) 
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Programming the Amiga's GUI in C 

PART II-MODULAR PROGRAMMING & AN INTRODUCTION TO WINDOWS 



by Paul Castonguay 



This is the second in a series of articles that unit help you take advantage of many of the custom 
features of your Amiga using the C Programming Language. In this issue you will find: 

1. A discussion of modular programming using the SAS/C, version 5.10A. 

2. A presentation of how windows are opened in the Intuition programming environment. 

3. Some background material (on disk & page 74) for understanding how to best 
configure your system. 

4. A detailed discussion (on disk) of the installation programs that appeared in the last issue 
of AC's TECH. 



Structured Programming, Modules 

One of the most important concepts in structured program- 
ming is the idea that a project should be broken down into pre- 
compiled modules. There are two reasons for this, First, it makes 
the solution of a complex programming task easier to deal with by 
treating it as a combination of several, more fundamental and 
easier to understand sub-tasks. Second, it saves time by removing 
the requirement that an entire project be re-compiled every time 
a modification is made to only one small part of it, or that a 
particular module be re-compiled every time it is imported into 
a different project. 

Last article we saw the development of a program (Libs.c) to 
open various "RunTime" libraries that we will use in most of our 
projects. We saw that it involved many issues, far too many to 
deal with every time we start a new project. We therefore want to 
develop a general solution that will be reusable in any new 
project. 

One way you could use the above mentioned program is to 
join (or merge) the source code of the Open_Libs() and Close_Libs() 
functions into that of other projects. Although that would be 
easier than rewriting those functions from scratch, it would still 
require that they be compiled along with the other project. 
Compiling is a time consuming process and we should not waste 
valuable development time doing it over and over again to the 
same functions every time we want to use them in a different 
project. For that reason every development package (like SAS/C) 
allows for the creation of compiled versions of functions (or 
collections of related functions) that can be joined to other pro- 
gramming projects not at the source code level, but at the object 
code level, by the linker. I call these compiled functions modules. 

Below 1 give the listing of Libs.c with the exception that this 
time there is no main() function. Recall from Standard C that 
every C program requires a function called main() (page 6 of "The 
C Programming Language", by Brian Kern ighan & Dennis Ritchie, 
Second Edition, Prentice Hall 1988, referred to in this article as 
K&R). Thus it does not represent a complete program. It is only 



a module. It is also available on the disk that comes with this 
magazine, so you don't have to actually type it in. Note that the 
version on disk contains extra comment lines not shown below 
that act as documentation. 



* include <intuition/intuiticnbas^,h> 
Hnclude <graphics/gfxfaase.h> 
sinclude libraries 'diskfont.h> 
^include <proto/exec.h> 
^include <stdic.h> 

idefine INTUITION_REV 33 
idetine GRAFHICS_RiV 33 
#define DISKFOWTJSV 33 



I* == GLOBAL pointers required by sysi 

struct IntuiticnBase *IntuitionBase - 
struct GfxBase "CfxBase = NULL; 

struct Library *DisklontBase = NULL; 



* == Functions in. this module === *> 



300L Open_Libs(VOIDI; 
VOID eiose_Libs{VQID); 



BOOL Open_Lir i : 



f (1 (IntuitionBase = [struct ir.tuitionEase *) 

OpenLibraryl" intuition, library", :NTUITION_R£V) ] 

.'.LCCan't load intuition, library. \n') ; 
retumlFALSE] ; 



: . 3fxBase - struct OfxBase *! 

OpenLibraryCgraphics.ltbrary", G3APHICS_KEV) ) ] 

print£( "Can't load graphics. library, \n"l ; 
Ciose_Libs(l; /* close IntuitionBase */ 
retumlFALSE); 



if : D: skfontEase = (struct Library *: 
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OpenLibrary I "diskfonc. library', DlStFOOTJlEVI I] 

printfCCan't load diskfont. library. \n'l : 
Close_Libs t ) r /* close In-.uitionBase S GfxBase */ 
return(FALSE); 



. . TR'JEI; 



VOID ciose_Libs(VOID) 



.ItionBase) 
:l:seLibrsry(f struct Library * I IntuiticTiBase) ; 

if (GfxBase) 

CloseLibrary ( [struct Library * I GfxBase] ; 

LskfoncBase] 

CloseLibrary (DiskfontBase) ; 



We now want to compile this module, but not link it (see 
background material on compiling and linking last issue). I will 
do this first from theSHELL window, the icon method will follow 
shortly. 

Copy the Libs.c file from the magazine diskette to your 
current working directory, either RAM:, RAM:My_Project, or 
SAS_Headers: depending on the size of your system and how you 
like to work. What follows does not take up much memory so 
don't be afraid to use RAM: on a 512K. system. 

Copy Source_Ccde/Libs/Design/SHELL_Versior./Libs.c to "* 

Notice the use of double quotes "" with nothing in between 
to copy a file into a current directory. This is a feature of version 
1.3 AmigaDOS. Next enter the following command: 

LC Libs 

This produces a file called Libs.o, representing the object code of 
the above listing. It is now a compiled module. 

Check Out the Size 

Use the AmigaDOS List command to see the size of the Libs.o 
file. On my system 1 get 684 bytes. That's pretty small, smaller in 
fact than the original source code (Libs.c) that produced it. Now 
to help you gain a better understanding of what is going on here 
take a look at the size of the compiled and linked program that 
you produced last issue. On my system it was 7240 bytes. The 
reason for this large difference in size between a program and a 
module is the fact that the program has been linked. It has had 
added to it the routines required to run it on the system. 

Just for the fun of it try running the above compiled module by 
entering the following command into a SHELL window: 

Libs.o 



My computer reports: "Unable to load Libs.o: file is not an object 
module". You see, a module does not represent a complete 
program. It is however in a compiled form, ready to be used in 
other programming projects. But before seeing how that is done 
I need to say a few words about compiler options. 

Compiler Options 

So far you have been merrily compiling and linking by 
entering tile LC command in a SHELL window, or by double 
clicking the "Build" icon on the Workbench, without giving too 
much thought as to exactly how that job got done. It just so 
happens that the LC program has a series of default settings 
(options) that it uses in the absence of any given by you. But 
default options do not satisfy every programming situation. 1 
therefore recommend that you learn a few important ones. 

From the SHELL window you specify compiler options by 
entering them on the command line after the LC or LCI command 
and before the name of the program you want to compile. You 
must also precede them with a hyphen, like this: 

LC -Lm nryprogram 

See the background material in the last issue of AC's TECH/ 
AMIG A , Rem ember tha t options are case sensi five, -Lm is not the 
same as -LM or -lm. 



LC's -c Option 

The -c option is called the compatibility option and it is used 
to activate certain features having to do with ANSI compliance, 
as well as compatibility with earlier compilers. This option is used 
in conjunction with one or more other letters, each representing 
a different feature. Below I describe the ones that I will use. 

-cf Option 

I'm sure you have noticed the extra effort that I have taken to 
write my functions in the style recommended by the new ANSI 
standard (K&R, page 26). This makes it possible for the compiler 
to pick up errors having to do with the number and type of 
arguments used in function calls. It does that by comparing 
function calls against their prototype definitions, and to work 
properly every function in your program must have a prototype 
definition. The -cf option forces the compiler to verify the pres- 
ence of a prototype definition for every function in your program 
and warn you if one is missing. 

-ci Option 

In a complex project the number of header files can be quite 
large, making it highly likely that you will accidentally #include 
a particular one more than once. The -ci options protects you 
againstthatby making the compiler suppress multiple inclusions 
of the same header file, using only the first one. 

-cs Option 

You should remember from Standard C that whenever you 
use a string constant in one of your programs the compiler must 
store it somewhere in memory. The statement: 



printf ("Hello World. \n'l; 
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causes the allocation of 14 contiguous (adjacent) bytes in memory- 
containing the above string, complete with a 'SO' to signal the end 
of the string. When the printf() function is executed it receives as 
input not the string itself, but the address in memory where it is 
located. 

String constants are used often in programs and occasionally 
the same one is used more than once in the same program. 
Perhaps there are several printfQ statements containing the same 
message, like this one: 

print f ("Error, program aborted: ! \n" I ; 

The -cs option causes the compiler to take advantage of this and 
create only one string in memory to serve the several printff) 
statements that use it, giving to each the address of the same place 
in memory. It makes your program more compact. 

■ct Option 

A fact of life that you must deal with when programming in 
the Amiga's Intuition environment is the heavy use of structures 
(K&R, page 128) and pointers to structures. You have already 
seen that something as simple as a pointer to a library is actually 
a pointer to a structure, specifically of type "struct InttiitionBase". 
It turns out that the accidental use of undefined structures can 
occur often in your programs as a result of either forgetting a 
necessary header file, or by making a simple typo error, like 
entering "Inluilionbase" instead of "IntuitionBase" (lowercase 
'b' instead of upper case 'B'). The -ct option causes the compiler 
to warn you if your program attempts to use a structure before it 
is defined. 

-cc Option 

A common practice when debugging programs is to corn- 
men tout certain parts, thus compiling the program with that part 
removed. It helps locate the exact location of bugs in your source 
code. However the compiler will get mixed up it the section of 
code you comment out has some comments within it. The -cc 
option allows the use of nested comments, comments within 
comments. It allows you to comment out any section of your 
program and not have to worry about whether or not there are 
comments within that section. 

To use all the above features together you combine them in 
a single option field with thee as the first character and the rest in 
any order, like this: 

LC -ctistc nrarogram 



-bl Option, Relative Addressing 

This option has to do with the way the MCS68000 micropro- 
cessor (the central processing unit inside the Amiga) specifies 
addresses in memory. It can do so either absolutely using a 32 bit 
number (ULONG), which can represent any address in memory, 
or relatively using a 16 bit number (WORD), which can represent 
addresses only as an offset from some other address. Relative 
addressing requires less machine code instructions, resulting in 



faster executing programs. However, it has the disadvantage that 
it is not able to reach sections of memory outside a single 64K 
segment. We will use the faster executing relative addressing 
mode (option -bl ) and in the event that our programs become too 
large, the compiler will warn us that it cannot reach all parts of it. 
At that point we will have to use the compiler option that specifies 
absolute addressing, which is -bO. 

Combining all the above options together for our Libs.c example 
we have: 

LC -bl -cfistc Libs 

or, calling the first and second pass compiler programs directly 
we have: 

LCI -bl -cfistc Libs 

Try the above commands from the SHELL window on the Libs.c 
module and confirm that the compiler produces a more efficient 
version occupying 656 bytes instead of the 684 produced earlier. 



-o Option. LCI, LCI, And the QUAD: Device 

The LC controlling program writes and reads the quad file 
(intermediate file produced by LCI) to and from the QUAD: 
device. However, the LCI and LC2 programs, when called di- 
rectly, do not recognize the QUAD: device. You may not want 
that. To force the LCI and LC2 programs to recognize the QUAD: 
device (perhaps to conserve memory, perhaps for smoother 
operation) you must use another option, the -o option: 

LCI -bl -cfistc -OQUAD: Libs 
LC2 -oLibs.o QUAD:Libs 

The above commands cause the quad file to be written to and read 
from the QUAD: device, and the object code (compiled module) 
to be placed in the current directory. Later in this article you will 
see that there is an easy way to deal with such long option fields. 

Compiling a Module from Icons 

If you have already tried to compile Libs.c by dragging it into 
a new project drawer (one created using SASCSetup) and double 
clicking the "Build" icon, you saw the system try in vain to link it 
as well. On ti two floppy system it probably complained that it 
could not locate the file "amiga.lib". On a hard drive system the 
BLinkprogram reported that_main was an undefined symbol. Be 
careful! Any attempt to run such a program will crash your 
machine. 

Nothing is wrong here. What you are seeing is a result of the 
fact that the icon method of compiling, lacking instructions to do 
otherwise, tries to link all programs that it compiles. But since 
Libs.c does not represent a complete program (it has no mainQ 
remember?) the BLink program experiences difficulties with it. 
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The Lattice Make Facility 

Please try the following little experiment. Single select the 
"Build" icon in any project drawer and then pick "Info" from the 
Workbench pull-down menu. The default tool is LC:LMK, not 
LC:LC as you might have expected. Thus double-clicking the 
"Build" icon invokes not the LC program but another one called 
"LMK". This program is usually referred to as "Lattice Make". Its 
purpose is to supervise the compiling and linking of your project. 
Let's try a short demonstration. 

A Short Working Example, Using Icons 

Copy the entire Source_Code/Libs/lCON_Version drawer 
from the magazine diskette to your current working directory, 
open it up, and double-click its "Build" icon. Libs.c compiles but 
this time no attempt is made to link it. Close the window and re- 
open it and you will see a new icon called Libs.o, vour new 
module. 

How Come it Worked? 

The ICON_Version of Libs has a new file inside called 
"LMKFile". Double-click its icon and the LSE editor will show 
you its contents: 

Libs.o : Libs.c 

LC -bl -cfistc Libs 

Copy LC: Icons ,'def_exe. info to Libs.o. info 

So il turns on; thai In compile a program you don't actually 
invoke the LC program directly. Instead you put instructions to 
do so in a file called LMKFile. Then the LMK program (invoked 
by double-clicking the "Build" icon) sees to it that those instruc- 
tions get executed. Notice that within the LMKFile I specified the 
f ull set of compiler options that we discussed earlier, i will discuss 
the exact syntax rules for the LMKFile instructions later in this 
article. You may now quit the LSE editor. 

The Power of LMK 

Double-click the "Build" icon again. This time Libs.c does 
not get compiled. Instead LMK reports that your project is up to 
date. Here lies the real power of LMK. It does more than just 
execute instructions to compile your modules, it also determines 
whether or not those modules need to be compiled in the first 
place. In this case it determined that Libs.c did not need to be re- 
compiled. Now double-click the Libs.c icon, re-save it ([RICHT- 
AMIGAJ-S), and then double click the "Build" icon again. This 
time LMK decides that re-compilation is required. 

LMK from the Shell 

The LMK program is not just a trick to allow you to compile 
modules using icons, it is useful from the SHELL as well. Let's go 
back to the SHELL version and compile the module again, this 
time using the LMK program. 

Delete the Libs.o module that you compiled from the SHELL 
earlier, then copy into that same directory all files from 
Source_Code/Libs/Design/SHELL_Version on the magazine 
diskette. 

Copy Source JTode/Libs/Desigi\/SHEU._Version to *" 



Now enter: 



LMK 



and the module gets compiled. Here is the corresponding LMKFile: 

Libs.o : Libs.c 

LCI -bl -cfistc -CQUAD: Libs 
LC2 -oLibs.O QUAD: Libs 

Notice that in the above script 1 called the first and second pass 
compiler programs directly rather than through the LC control- 
ling program. I did that in the interest of memory efficiency, for 
owners of 512K systems. Enter the LMK command a second time 
and it will report to you that your project is up to date. 



It Isn 't Magic 

The LM K program relies on the da te / time stamp of your files 
for its operation. You should now begin to appreciate why in the 
51 2K installation instructions (last issue) I emphasized the impor- 
tance of entering the correct date and time every time you use 
your computer. In the above example the LMK program com- 
pared the time stamp of Libs.c with that of Libs.o to determine 
whether or not Libs.c had been modified since the last compila- 
tion was performed. 

LMK Helps You Organize Your Projects 

A project can consist of many modules, each one dependent 
in some way on one or more of the others. A modification to one 
might require that certain ones be re-compiled, while others 
remain unaffected. Only you will know for sure because it is you 
who is designing the project. But as your project gets larger and 
the nu mbe r of modules in it increases, even you w ill begin to loose 
track of exactly how they depend on each other. The LMK 
program can help you maintain control over such issues by 
following the instructions that you specify in the LMKFile. You 
write these instructions for each module at the same time that you 
design it, when you are most familiar with how it affects and 
interacts with other modules in the project. 

Once the instructions for a particular module are written you 
can essentially forget about them, the LMK program will execute 
them as required whenever you enter the LMK command, or 
double-click the "Build" icon. If you design more modules you 
simply add more instructions to the LMKFile. Each time you 
invoke the LMK program it will compile only those modules 
which are new or have been modified. Naturally there are some 
syntax rules that you must learn in order to write instructions in 
the LMKFile, but first let's finish our module example. 

Testing Our Module 

You must always test a module before using it in other 
projects. To do that you write a driver program, a short mainQ, 
that calls the functions in the module. This is very similar to the 
example last issue except that this time the test program is in a 
different file than the functions, and the functions are in a com- 
piled form. 
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Recall from standard C that if one part of your program 
wants to use a variable or function that is defined in another file 
you must use an "extern" declaration for it (K&R, page 80). Our 
module contains two functions, Open_Libs() and Close_Libs(),as 
well as three pointer variables that must be global in scope. Any 
project that wants to use this module must therefore make extern 
declarations to those functions and pointers. But wait a minute, 
isn't that a lot of work? After all, the whole idea of building the 
module in the first place was to protect us from exactly these 
kinds of internal details. 

A common way of handling this complexity is to make a 
header file for the module. When you want to import the module 
into a new project you make all its required declarations by 
putting into your source code one simple #include statement to 
the module's header file. This is another example of the formal 
principle called "Information Hiding". Below 1 give you the 
header file, the test program, and the LMKFile that together link 
and test the Libs.omodule. Note that the versionof Libs.h on disk 
contains comments not shown below. These are detailed descrip- 
tions on how to use the functions in Libs.o, making it easier for 
you to do so at a later date. I'll have more to say about this next 
issue. 



MODULE HEADER FILE 



. 



/* 

/* AC'S TECH /AMIGA 
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.'* === GLGEAI pointers rehired to use Libs.o 

GLOBAL struct IntuitionBase "IntuiticnBase; 
GLOBAL strict GfxBase "GfxBase; 
GLOBAL struct Library "DiskfcntBaser 



Functions within Libs.o module === */ 



GLOBAL BOOL Open_Libs (VOID) ; 
GLOBAL VOID Close_Libs(VOID| ; 



MODULE TEST PROGRAM 



1* 

r 

/• AC TECK 


Test_Libs.c 


Volume 1 


, Number 1 


V 


(include <stdio.h> 
(include <stdlib.h> 
(include <libraries7dos.h> 
(include <proto/dos.h> 











(include "Libs.h" 

VOID main! int argc, char "argv[i); 

VOID main (int argc, char *Mgvll) 
{ 

ifdOpen.LibsOl 
I 

printf ("Trouble opening libraries\n"); 

Delay (100); 



I 



Belaj 100); 

Close_Libs ( I ; 
exit (RE: 



TEST LMKFILE 



Test_Libs : Test_Libs.o Libs.o 

BLink FROM LIB:c.O*l - .Libs.o TO Test.Libs LIBRARY LIB:lc. lib 

Test_Libs.o ; Test_Lib$.c Libs.h 
LC -bi -cfistc Test_Libs 



You can find these files on the magazine diskette in the 
directory: 

So'jrce_Code/Libs/Test/SHELL_'v'ersion/ 



Source_Code/Libs/Test/ICON_version/ 

depending which method you choose for using your compiler. 
Double-click the "Build" icon, or enter LMK in a SHELL window, 
and witness the compiling and linking of the project. You will see 
that the file Libs.c is not re-compiled. In fact, it isn't even present 
in that directory. Instead, the Libs.o module is linked directly into 
the project by the BLink program. Congratulations, you have just 
built vour first pre-compiled module and linked it into a project, 
albeit a very small one. 

You might be wondering about a few things in the above 
program. First of all I have changed the type for the function 
main() from previous examples. I am now following the form 
suggested in the ROM KERN AL manual, as well as the new ANSI 
standard. The function main() is defined as type VOID, meaning 
that it will return no value. To terminate the program I use the 
exit() function which transfers control back to the operating 
system and passes to it an integer value. To remain compatible 
with other AmigaDOS programs, I return the values defined in 
themacrosRETURN_OK,RETURN_WARN,RETURN_ERROR, 
and RETURN_FAIL. These contain values of 0, 5, 10, and 20 as 
defined in the <libraries/dos.h> header file. Another change to 
main() is the use of the variables argc and argv for accepting 
command line arguments, even though my program doesn't 
actually make use of them. This is becoming the new accepted 
Standard C form for the main() function of any program. 

The above changes require that I add a prototype declaration 
for mainf). "Why not do that in a header file?", you ask. Well, if 
you look in <stdlib,h> (line 79) you will see that there is one there, 
but it has been commented out. If you remove the comments and 
re-install your header files you won't have to put a prototvpe 
declaration for main() in your programs, assuming that you 
#include the <stdlib.h> header file of course. But be warned that 



printf ("intuition. library = lu\n", IntuitionBasel ; 
printf ("graphics. library = %u\n", GfxBasel; 
printf ("diskfo.1t. library - lu\n", DiskfontBasel ; 
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you r compiler may now compla in if you try to compile progra ms 
that use the older integer type main() or that don't use the argc 
and argv arguments. Most C textbooks examples are still using 
the old form. 

Each #include statement in the Test_Lihs.c program is made 
fora different reason. <stdio.h> contains the prototype definition 
of the printfQ function. <stdlib.h> contains the prototype defini- 
tion of the exit{) function. <proto/dos.h> contains the prototype 
definition of the DelayQ function. And finally "Libs.h" contains 
the prototype definitions and global variable declarations for the 
Lib.o module. Notice that angle brackets <> are used to indicate 
header files that are stored in the INCLUDE: device, where 
system header files are located, and quotation marks "" are used 
to indicate header files that are stored in the current directory, 
where project header files are located. 

The above example required that the Libs.o and Libs.h files 
be in the current directory. I put them there for you this time, but 
in the next example you will have to do that yourself. 

You must now be careful to not loose the module Libs.o and 
its related header file Libs.h. Together these two files represent an 
easy to use, streamlined solution (in the form of a pre-compiled 
module) for opening the Amiga's "Run Time" libraries. You have 
worked hard to produce that module and you don'twantto waste 
valuable time doing it again. In the future you will use it by 
copying the Libs.o and Libs.h files into the drawer (directory) of 
other projects. In the meantime you need a safe place to archive 
it. I recommend that you start a special library diskette to hold all 
your pre-compiled modules, as well as their related tiles. 



Suggested File Structure 

I said last issue that programming in C was largely a matter 
of organizing your work in such a way that it becomes usable in 
most programming situations. With that in mind the way you 
archive your work is very important. If you archive Libs.o and 
Libs.h alongside other files, like Libs.c and LMKFile, you may 
forget exactly which files you're supposed to copy into other 
projects in order to use the module. At the same time you must 
archive all files that were used in its design in the event that you 
want to modify it at some later date. 

Figure One shows a suggested filestructure for archiving the 
above module. Notice that the only files visible in the Libs 
directory are Libs.o and Libs.c, the ones you need to copy to other 
projects in order to use the module. Design and Test are directo- 
ries. At the same time all support files needed for its design and 
verification are safely tucked away in their own respective direc- 
tories, available for future program maintenance. 

Making an LMKfile 

Now that you have seen the LMK program in operation, and 
convinced yourself of the need to use it, you need to learn the 
syntax rules for writing instructions into the LMKFile. The main 
idea behind these instructions is to tell the LMK program what 
files to produce, when, and how. This is done by giving it a series 
of target files, dependent files, and actions. 
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TARGET FILES: Files that you want LMK to produce 

DEPENDENT FILES: Files that you want to affect the 
generation of the target files. 

ACTIONS: Specific instructions for producing target 
files from their dependents. 

Target files are specified as a name followed by a space, then a 
colon. They must be written starting in the first column (along left 
edge of editor window). In the Test_Libs example the files 
Test_Libs and Test_Libs.o are entered as target files. They are files 
that you want the LMK program to produce. 

Test_Libs : Test_Libs.o Libs.o 

BLink FROM LI3:C.o+Test_Libs.o+Libs.o TO Test_Libs LIBRARY LIB:lC. 

Test_Libs.o : Test_Libs.c Libs.h 
LC -bl -ctiste Test_Libs 



Dependent files are listed after the colon on the same line as the 
target file that you want them to affect and they are separated by 
spaces. Thus we have the form: 

target file : dependent file list 

In the above example Test_Libs.c and Libs.h are dependent files 
of the target file Test_Libs.o. They are used to produce it. Simi- 
larly, Test_Libs.o and Libs.o are dependent files of Test_Libs. 

Actions are specified on the line or lines immediately follow- 
ing the "target : dependent list" and are indented one tab. They 
contain specific instructions on how to produce a target from its 
dependent files. In the above example the line "LC -bl -cfistc 
Test_Libs" tells LMK how to produce Test_Libs.o from Test_Libs.c 
and Libs.h. Note that the target file Test_Libs.o is itself a depen- 
dent file of Test_Libs and appears as such in the first instruction. 

The order of appearance of each target file in the LMKFileis 
in reverse to how it is produced. The rule to remember is that no 
target should appear earlier in the file than another for which it is 
also a dependent. In our above example the first entry, Test_Libs, 
is not a dependent file of any other target and therefore appears 
before all others in the file. However Test_Libs.o is a dependent 
of Test_Libs. Therefore the target Test_Libs.o must appear later in 
the file than the target Test_Libs. 

A blank line is use to separate each group of targets, depen- 
dents, and actions. 

Date/Time Stamps 

If a target file does not yet exist (as is the case when you are 
compiling a file for the first time) the LMK program executes its 
action lines. On the other hand if the target file already exists the 
LMK program checks the date/ time stamp of all its dependents. 
If any dependent file has a date/time stamp later than that of the 
target (as would be the case if you made a modification to one of 
them since the last time the project was compiled) the LMK 
program will execute the action lines. But if the date/ time stamps 



of all dependent files are earlier than that of the target (meaning 
that no modifications were done since the last compilation) the 
LMK program will decide that the last compilation is still valid 
and it will not execute the action lines. 

Look at the following "target : dependent" relationship 
(again from the above example): 

Test_Libs.o : Test_Libs.c Libs.h 
LC -bl -cfistc Test_Libs 

The file Libs.h is listed as a dependent file of Test_Libs.o. 1 did 
that because the Test_Libs.c file contains an #include statement 
for Libs.h. Thus any modification to Libs.h could affect the target 
in some way. But Libs.h is not part of the action line. That's 
because it is #included in the Test_Libs.c file, getting processed 
automatically when Test_Libs.c is compiled. This example dem- 
onstrates how a project consisting of several modules, each with 
its own header file, can easily get out of control if modifications 
are made to certain files without properly re-compiling certain 
others. A change to Libs.h requires that Test_Libs.c be re-com- 
piled and forgetting to do so would cause that change to not get 
incorporated into your project. As the number of modules in your 
project increases you may begin to loose track of such issues. The 
LMK program in conjunction with the instructions that you write 
in the LMKFile allows you to work on your project with a 
minimum of compiling and without having to think out the 
dependency of each module every time you make a modification 
to one of them. 

Warning About Dragging Modules 

Note that copying a project by dragging its drawer icon (on 
the Workbench screen) changes the date/ time stamp of all its files 
at the new location. Thus a project that is up to date in your RAM 
Disk may no longer be so when you archive it to a diskette. If you 
later drag that project back into RAM: and double-click its "Build" 
icon the LMK program may decide to re-compile the whole thing 
all over again even though it isn't really necessary. But even more 
importantly you may have wanted to keep an accurate record of 
when modifications were last performed on each module file in 
vour project. 

Keeping a Date 

To copy files without destroying their original date/time 
stamps you must use the Copy command from a SHELL window 
with the "clone" option. Note that Commodore has defined the 
xcopy command (as an alias name) to be equivalent to copy with 
the clone option. 

Copy RA!<!:Current_Work to Modules:Libs/Design clone 



XCopy RAM:Current_Work to Modules :Libs/Design 

Either above command copies all files in the RAM:Current_Work 
directory to the Modules:Libs/ Design directory preserving all 
date/time stamps. 
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Windows In Intuition 

The most important aspect of any programming environ- 
ment is how it interacts with the display screen. You can't create 
much of a program without showing something on the screen. In 
the case of the Amiga this is especially important since its graphic 
processing capability is far superior to any other computer in its 
class. Many people purchase the Amiga specifically to write 
programs that cause things to occur on its display screen. To meet 
that need Intuition provides a wide range of functions, each 
involving a rather large number of details. The key to dealing 
with the complexity of all this is to break each Intuition function 
down into its most elementary operational steps. By doingsoyou 
will discover that many of them work according to the same 
general operational theme, thus facilitating the learning of all of 
them. Here is the theme used by most functions that create 
graphic objects; 

1. Declarea structure in which to storea description of the graphic 
object you wish to create. This will not be the graphic object 
itself, but only a description of it. 

2. Declare a pointer that will eventually hold the address of the 
graphic object you wish to create. Note that this is not an 
instance of the graphic object, only a pointer to one. It is usually 
initialized to NULL. 

3. Open "intuition. library" if you have not done so already. 

4. Assign to each member of the description structure whatever 
characteristics you want your graphic object to have. This is 
usually done with a series of assignment statements. 

5. Call the Intuition function that creates the object using as an 
argument the address of the description structure declared in 
step one and assign the value returned by the function to the 
pointer declared in step two. Note that it is a common theme for 
Intuition functions to return the addresses of the graphic 
objects that they create. Often a cast (K&R, page 45) is required 
when assigning the address returned by a function. 

6. Test the value returned by the function to determine if the 
object was properly created. Usually you will want to see if it 
is a legal address or NULL. Null signifies that the graphic object 
was not created and you must take corrective action. 

7. Use the pointer to the object (as well as other pointers derived 
from it) throughout your program to access its features or to 
control it in different ways. 

8. Close the object before your program terminates, removing it 
from the screen and returning memory back to the system. 

This eight point operational theme will take vou a long way 
in vour studv of intuition. Of course what you actually do with a 
graphic object may vary greatly from program to program, but 
the above theme often forms a background plan around which 
your program works. The Intuition function that is used to open 
a window follows the above theme very closely. 



Figure One 
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The Open\Vindow( ) Function 

Your knowledge of the Amiga so far should be enough that 
I don't need to tell you that a window is a rectangular area on the 
screen that is used by your programs to display the results of 
various text and graphic processing. But you should know a bit 
more than that before attempting to open a window in C. Win- 
dows can be of different sizes and located at different locations 
within their parent screen. They have the ability to display colors 
using a concept called "color indirection", in which a large 
number of possible colors are accessed indirectly through a 
smaller number of hardware Pen registers. 1 he total number of 
different colors that they can display simultaneously dependson 
a property of the window's parent screen called depth. Windows 
can also have attached to them gadgets that allow them to be 
positioned and re-sized by the user independent of your pro- 
gram. 

This long list of characteristics and much more can and 
should be studied initially in BASIC rather than C. If you are 
unfamiliar with any of them I recommend that you do that. 
Naturally I will demonstrate how each is implemented in C, but 
1 cannot spend time here explaining the features themselves. I 
recommend the text "Advanced AmigaBASIC", by Halfhill and 
Brannon, Compute Publications, 1986. 
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Figure Two 

The use of OpenWindow( ) 
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Within the context of Intuition a window is a graphic object 
created by the OpenWindowQ function. This function accepts as 
an argument the address of a structure thatcontains a description 
of the window you want, and it returns the address of the window 
that it creates for you, or a NULL if for some reason it cannot fulfill 
your request. Your program will interact with this window object 
primarily by knowing its address. Naturally C, being a high level 
language, provides the concept of pointers (K&R, page 93) to deal 
with such issues and as a result operations involving windows 
rely heavily on the use of various pointers. But lets start at the 
beginning. 

Here are the operational steps required to create and use a 
window: 

1. Declare and initialize a structure of type "New Window" to 
hold a description of the window you want to create. The 
definition (template) of the NewWindow structure appears in 
the header file <intuition/intuition.h>. 



3. Open "intuition. library" if you have not already done so. 

4. Using a series of assignment statements store in each member 
of the NewWindow structure the characteristics of the window 
that you want. 

5. Call the OpenWindowQ function using as an argument the 
address of the description structure and assign the value re- 
turned by the function (address of the window created) to the 
pointerdeclared in step two. Cast the assignment to the correct 
type. 

6. Test the value that was returned by the OpenWindowQ func- 
tion. It will be either a legal address for a properly created 
window, or a NULL if for some reason one could not be created . 
Take corrective action if it is NULL. Any attempt to use a 
window through a NULL pointer will crash your machine. 

7. Use the pointer to the Window (as well as other pointers 
derived from it) throughout your program as an argument in 
various functions that display text and graphic images. 

8. Close the Window before your program terminates, removing 
it from the screen and returning memory to the system. 

See Figure Two for a graphic representation of the operation of 
opening a window. 

NewWindow Structure 

This is the structure in which you store all the characteristics 
of the window you want the OpenWindowQ function to create for 
you. I call it the description structure. Like ail structures it consists 
of a list of members of different types (K&R, page 127). View it as 
a kind of shopping list. Below 1 list its members as defined in 
<in tuition/intuition. h> header file, with the exception that 1 have 
removed all the comments. 

struct MewWifldow 
i 

£::; = : l-,::. 

SHORT TopEdge; 

SHORT Width; 

SHORT Height; 

UEYTE DetailPen; 

UBYTS BlockPen; 

ULONG IDCMPFlags; 

ULONG Flags; 

struct Gadget "FirstGadget; 

struct Image 'Checkmark; 

UEYTE 'Title; 

stnr-r Screen "Screen; 

struct BitKap "BitM 

SHORT MinHeight; 
USHORT MaxWidth; 
.::..:: ::._■_:-. ■.. • 
OSBOM Type; 



Declare a pointer to "struct Window" to hold the address of the 
window that will be created by the OpenWindowQ function. 
Note that this not an instance of a Window structure, but only 
a pointer to one. Initialize this pointer to NULL, The definition 
(template) of the Window structure appears in the header file 
<intuition/intuition.h>. 



Some of them are self-explanatory, while others seem a little 
obscure. Let's go through them all quickly, just to get a general 
idea of what they do. 
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The LeftEdge and TopEdge members of this structure refer 
to the position of those edges of the window from the top left 
corner of its parent screen, measured in pixels. Width and Height 
are its size, also measured in pixels. The DetailPen member refers 
to the hardware color register used for any text that you want to 
appear in the window's title bar. BlockPen is the register used for 
the background of the title bar and borders (if any). Most win- 
dows use register (blue) for DetailPen and 1 (white) for BlockPen, 
but you may use whatever registers you like. The IDCMPFlags 
member refers to a special message system that is used to commu- 
nicate with the window via the keyboard or mouse. The Flags 
member refers to several features, such as whether the window 
will have system gadgets, whether it will be active when it opens, 
or how it will deal with remembering its contents after being re- 
sized or temporarily covered up by other windows. Some of these 
features affect the previous IDCMP message system as well. The 
Gadgets and CheckMark members are used if you want the 
window to have gadgets or a menu checkmark of your own 
design. The Title member points to a string constant that you 
want to appear in the window's title bar. The Screen member 
points to the screen in which you want your window to be placed. 
The BitMap member points to an area of display memory re- 
quired if you want to use a concept called SUPER_BITMAP, 
which is another approach to having your window remember its 
contents after being re-sized by the user. MinWidth through 



MaxHeight refer to the dimension extremes beyond which you 
do not want the user to adjust the size of the window. And finally, 
type specifies whether you want your window to appear in the 
Workbench screen or i n one tha I vou crea te voursel f - more about 
that next issue. 

I understand that the above overview of the NewWindow 
structure was very superficial. Don't worry, I will come back to it 
next issue. It is more important now that you learn the general 
operation of the OpenWindowQ function and not get bogged 
down bv details. Besides, as the following example will demon- 
strate, those members that control unfamiliar, advanced features 
can simply be set to NULL. 

First Window Example 

Ova te a project drawer and copv into it the First_Window.c 
and its corresponding LMKFile file from the magazine diskette. 
Then copy into that same drawer the Libs module (Libs.o and 
Libs.h). Do you understand why Libs.c is not needed? 



' 






■ 
• 
■ 


: ! _ 


• 

Volura 1, Miabec 3 ■/ 



- 

Jinclude <protc Lntuition.to 
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((include <proto.'graphics.h> 
((include <proto.'dos.h> 
((include <stdio.h> 
((include <stdlib.h> 

(include 'Libs.h" 

VOID nainlint argc, char *argv[]l; 



/* =-- Step 8: Close window === V 

if (MyWindcw) 

CloseWindow(MyWindow) ; 

Close_Libs(); 

exit(RETURN_OKI; 



VOID nainlint argc, char *argv[]l 
{ 

," === Step L: Declare description structure === •/ 

struct NewWindow Window_Description; 

t* --- Step 2: Declare and initialize Window pointer —- */ 
struct window 'MyWindow = NULL; 



FROGRAM = First_Window 
LCFLAGS = -bl -cfistc 

S(PROGKAM): S( PROGRAM }.o Libs.o 

BLink FROM LIB:CO*S(PSCGR?.M).0+Lib5.0 TO S(PROGRAM) LIBRARV LIBllc.lib 

SfPROGKAMl.o: S ( PROGRAM! .c Libs, h 
LC $(LCFLASS) $< PROGRAM) 



/■ === Step 3: Open Libraries to use Intuition === */ 
ifl!Open_LibsO) 



I 



print f ("Trouble opening libraries^* I; 

DelayllOOl; 

exit(REnjRH_WARNI; 



Step 4: Assign description structure Trainers. 



WindowJJescript ion. Left Edge 
Window_Description,TopEdge 
Window_Descript ion. Width 
Window_Description. Height 
Window_Description.DetailPen 
Window_Description. BlockPen 
Window_Descript ion. Title 
Window_Descript ion. Flags 



= 100: 
= 50; 
= 400; 
= 100; 
= 3; 
= 2; 

- "My First Window'; 

- ACTIVATE I SMART_REFRESH; 



Window_Description. Screen = MILL; 
Windcw_Description.Type - WBENCHSCREEN; 



Window.Description.IDCMPFlags =. NOLL 

window_Description.FirstGadget = NULL 

Windcw_Description.CheckMar)c = NULL 

Window_Description.Bit.Hap - NULL 

Window_Description.MinWidth = 

Window_Description.MinHeight = 

Window„Description.MaxWidth = 

Window_Description.MaxHeight = 



/■ === Step 5; Call Openwindowtl function and assign return === */ 
/* === address to Window pointer. === * 

I* --- Step 6: Test value returned by OpenWindow. === */ 

if I! (MyWindow= (struct Window *IOpenWindow(swindow_Description)l) 
I 

printf ("Trouble opening MyWindowVn" ) ; 

DelayllOOl; 

Close_Libs(]; 

exit(RETURN_WARN); 



Step 7: Use window : 



*/ 



Set APen I KyWindow- >RPort , 1 ) ; 

Move(MyWindow->RPort, 93, 501; 

TextlMyWindow->RPort, "Kelp me, I'm stuck in here. \n", 27].- 

Delay (500 1; 



Let's start with the subject at hand, the opening of the 
window. Step 1 createsan instance of a NewWindow structure in 
which we will store a description of the window we want. I 
named it Window_Description. You are free to use any name you 
want. Step 2 declares a pointer of type "struct Window", names 
it MyWindow (you can use any name) and initializes it to NULL. 
This is the pointer to which you will assign the address of the 
window when it is returned by the OpenWindowQ function. Step 
3 opens "intuition. library". Step 4 stores a description of the 
window into the description structure, using a series of assign- 
ment statements. 1 have arranged them in the listing into related 
groups. 

Of particular interest are the NULLs at IDCMPFlags, 
FirstGadget, CheckMark, and BitMap, which mean that I do not 
want to use those features. Notice the NULL at the Screen 
member and "WBENCHSCREEN" at the Type member. To- 
gether these two assignments cause the window to open up on the 
Workbench screen. The macro "WBENCHSCREEN" is defined 
in the header file <intuition/screens.h>. The MinWidth through 
MaxHeight members are all set to zero because the window I 
want to create will not have any re-sizing capability. Now look at 
the DetailPen and BlockPen members. The values I have chosen 
should demonstrate beyond any doubt what each one does. The 
result will be an orange title (color 3 in DetailPen) in a black 
border (color 2 in BlockPen). 

The last member I want to mention is Flags. I have assigned 
it the value "ACTIVATE". This is a macro defined in the header 
file <intuition/intuition.h>. As you know, windows can be acti- 
vated or de-activated using the mouse. De-activated windows 
have a hazed or ghosted appearance in their title bar. I asked for 
the window to be automatically activated to improve the appear- 
ance of its title bar. Step 5 and 6 of the general operational theme 
are accomplished together in one tight "if block". The window 
pointer is assigned, logically inverted, and finally tested for 
success all in one line using the popular functional calling style 
that I presented last issue. 

In the event that a window cannot be created, the NULL 
returnedby the Open Window() function getsinverted to 1 (TRUE) 
causing the if() statement to succeed and the corrective action 
inside the block to execute, safely terminating the program. 
Otherwise, the window address is considered valid and the 
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program pushes onward. Step 7 involves actually using the 
window. To do that you usually have to specify the window 
pointe r, or an address derived from it, as an a rgument in a graphi c 
function. I demonstrate this with three lines that together position 
and display a message inside the window. Never mind exactly 
how these functions work, you will learn that soon enough. For 
now simply view them as the part of the program that accom- 
plishes step 7 of the operational theme. Finally, and with no 
surprise, comes the last step which closes the window. To do that 
you must call the Intuition function CloseWindow() using as an 
argument the pointer to the window that was assigned in step 5. 
Notice the similarity to the closing of libraries last issue. Although 
it is not necessary in this program it is best to test the pointer 
before closing the window, otherwise the computer could crash. 

Initializing Structures 

There is another way in Standard C to initialize members of 
a structure. The method consists of initializing the entire struc- 
ture (all members) automatically when it is declared, like this: 



struct NewWirsdov window_Description ■■ 



(100, 50, 100, 100, 3, 3, 
NULL, ACTIVATE, NULL, NULL, 

■Hy First Window, null, null, 

0, 0, 0, 0, KBFJOSCBEF-J) ; 



The above instruction causes the compiler to initialize each 
member of the NewWindow structure consecutively using the 
values appearing in the list. This method is preferred by some 
programmers over a long series of assignment statements be- 
cause it is both faster to type in and faster to execute. But there are 
problems with this method. If one number in your data is out of 
place then nil member- following it may end up receiving wrong 
values. But more importantly, this quick method does not use the 
structure's descriptive member names. You need those names in 
order to understand the exact purpose of each piece of data in the 
program. 

If you want to verify the purpose of one number in the above 
list you will have to search through the header file system for the 
structure's template and then count down its list of member 
names until you get to the one you want. Chances are you will 
make a mistake. In contrast initializing that same structure using 
individual assignment statements puts those member names 
right within the block of code where they are used, where they can 
help both you and others understand the program's operation. In 
addition, individual assignment statements can be arranged in 
any order. Grouping related ones together, as 1 did earlier, helps 
to better understand their collective operation. 

One more reason for not using the above quick initialization 
method for a description structure is that you will almost cer- 
tainly want to write a pre-compiled module that contains a 
function capable of opening windows having a range of charac- 
teristics. This is in accordance with the philosophy of structured 
programming and information hiding, and we will be doing that 
next issue. You will see then that part of the design of such a 
function is the interpretation of arguments passed to it and the 
assignment of values to corresponding members of the descrip- 
tion structure. In such situations the above quick initialization 
method will be of little value. 



LMKfile Macro Substitutions 

The LMKFile for this last example uses a new concept, macro 
substitutions. Two macros are defined at the top of the file for 
substitu tion at different loca tions wi thin it. The firs t of these is the 
line: 

PROGRAM = First_Windcw 

This line defines the word "PROGRAM" to be equivalent to the 
text string "First_Window". The dollar sign operator with paren- 
theses causes the macro to be substituted at different locations 
within the file. Thus the instruction: 

S (PROGRAM): S I PROGRAM) . o Libs . 

BLink FROM LIB: C.OtS (PROGRAM) ,o*Libs.o TO 5 (PROGRAM) LIBRARY LIBtlc.lib 

is equivalent to: 

:::--_..:-i3w : First_Windov.o Libs.G 

BLink FRC« LI3:c._+First_WLr._ow.o+Libs.o TO Fir5t_Kir.Gov LIERAHY LIBrlc.lib 

The target file First_Window is produced by linking 
First_Window.o, Libs.o and the system startup code LIB:c.o. 

Similarly the second macro: 

LCFLAGS = -bl -cfistc 

gets substituted at the proper place as an option field for the LC 
command. 

Macro substitutions allow you to use the same LMKFile for 
several projects. You just change the macro definition of PRO- 
GRAM and it will compile whatever new project you want, 
assuming of course that you want it to be compiled and linked in 
exactly the same manner. 

Example Programs on Disk 

Modular programming is more practice than theory. To help 
you along with that I have included on disk two example projects 
that you can compile yourself. They are called Ball_Anim and 
LLne_Anim and each represent an example that I will be present- 
ing next issue. They will help you gain valuable experience 
compiling projects consisting of pre-compiled modules. Note 
that you will have to copy the Libs module (the Libs.o and Libs.h 
files) info each project drawer. I'm expecting you to do that 
yourself. Once you have done that you can go ahead and double- 
click the "Build" icon, or enter LMK into a SHELL window. 
Observant readers will notice the presence of a second module 
called Display. o, installed in each project drawer. Don't worry 
that you do not yet understand the purpose of this module. I will 
be presenting it next issue. Your main goal here is to go through 
the motions of compiling the project, and that won't change 
whether you understand the exact purpose of the modules or not. 
Notice also that the source code for Display.o is not present. It 
isn't necessary. Like Libs.o it is a pre-compiled module that gets 
added to your program by the BLink program. The only pro- 
grams that actually get compiled are Ball_Anim.c, Line_Anim.c, 
and the various header files. 
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I have altered the proper instructions into the LMKFile for 
each project. Make sure you look at it and try to understand its 
instructions. 

For those readers who do not own SAS/C I provide com- 
piled versions of both projects in the drawer called 
"Compiled_Programs". Simply double-click their icons. Perhaps 
after seeing them you will want to learn more about how they 
work, and even try your own hand at writing similar programs 
yourself. An Amiga with a C compiler is an exciting combination. 
Note however that these programs are not intended to be com- 
petitive animations in their own right. Rather, they are instruc- 
tional examples that will be used next issue to help me present 
some fundamental programming concepts. 

More On Disk 

Before leaving this article remember that the diskette that 
comes with this magazine contains some valuable background 
material to help you better understand the configuration pro- 
grams given in the last issue of AC's TECH/AMIGA. You will 
also find that material helpful if you want to make modifications 
to those installations yourself. 

Next Issue! 

Today I barely introduced the concept of opening windows 
in Intuition. Next issue I will present some of its more intricate 
details, as well as a streamlined version in the form of a pre- 
compiled module, called Display.o (you knew that was coming 
didn't you). I will include in its design the ability to display 
different resolutions and number of colors. In addition I will 
present a subject that is almost always ignored in programming 
articles but which is very important, screen scaling. If you have 
ever programmed in AmigaBASIC you probably know that the 



dimensions and position of graphic images are measured using 
pixel numbers, measured from the top left corner of a window. 
Many of the Amiga's graphic commands accept these pixel 
numbers directly. Unfortunately most graphic images depend on 
some sort of mathematical equation which cannot be expressed 
directly in terms of pixel numbers. I have therefore designed into 
the Display.o module two scaling functions that will allow you to 
express equations in their conventional form, while at the same 
time pass to the Amiga's graphic functions their corresponding 
pixel numbers. In fact, many of our programs will be written in 
such a way that they work regardless of the actual number of 
pixels in a window. Hard to believe? Try the following short 
experiment in the Line_Anim.c program. Modify line 46 from: 

if(!Cpen_Hy_Screeni"I- s .CEHIGH4", fcTy_screen, tay_svpl) 



lo 



if ( !0peaJJ/_Screen['LCW4", fey_5creen, &my_svp) ) 

That is, change the resolution from LACEHIGH4 to 
LOVV4 (high resolution interlace to low resolution non-interlace, 
more about this next issue). Compile the program again and 
execute it. Notice that even though the text characters are now a 
different size (larger) they still appear properly centered in the 
window. Also, the animation itself remains well behaved, pre- 
serving its original physical size despite of the fact that the 
number of pixels on the screen, both horizontally and vertically, 
is now only half of what it originally was. This kind of resolution 
independence does not happen automatically but is a result of the 
way we write our programs. I hope to see you next issue. 
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Now We Are Also The Service Bureau 
Amiga Users Everywhere Can Depend On For 
High-Quality, Professional Imagesetting! 



The same company that Amiga users 
everywhere depend on for all their 
informational needs now also provides a 
full range of imagesetting services to Amiga 
desktop publishers, and anyone requiring 
high-resolution output of their Amiga text 
or graphics files to film or RC paper at up 
to 2400 dpi! 



We are the publishers of Amazing 
Computing, AC's GUIDE, and AC's TECH. 
So we know the Amiga - and we know what 
you need in a service bureau! 

The Service Bureau of PiM Publications 
offers the entire Amiga community fast, 
efficient, professional imagesetting services 
at reasonable prices. 



Call toll free 1-800-345-3360 today for more information! 
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Recently, we were ordered by 
U.S. military officials to explain to 
their complete satisfaction just 
what a SuperSub is (as we all 
know, it's the best subscription 
deal around for Amiga users, 
since it includes both Amazing 
Computing and ACs GUIDE). 



Arftftftft 



1 hen, a prominent Congressman 
wired to ask us if we would testify 
before a top-secret subcommittee 
as to whether or not we can pro- 
duce a single prototype SuperSub 
for less than $500 million (is this 
guy kidding? - a one-year 
SuperSub costs just $36 - and we 
can produce one for anybody*). 



-»**■& 



Finally, a gentleman called us 
from Kennebunkport and told us 
to read his lips, but we told him 
we couldn't, because we don't 
have a picturephone. 

And then he ordered a SuperSub, 



AC'S SuperSub - 
It's Right For You! 

call 1-800-345-3360 
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An Introduction to 
Programming for HAM-E 




by Ben Williams, Black Belt Systems 



About the HAM-E 

The HAM-E is an external "display enhancer" for all 
Amiga models, NTSC and PAL. The term "HAM-E" stands for 
"Hold-And-Modify-Expander". The HAM-E actually provides 
two new display modes. One is 256 simultaneous colors from a 24 
bit palette. The other is 262144 simultaneous colors using an 8 bit 
per pixel extended HAM mode. The extended HAM mode has 
been designed such that it is much less prone to "fringing" than 
the HAM mode that is standard with the Amiga. The 256 color 
mode isn't HAM, and as such has no drawbacks whatsoever. 

The HAM-E provides the Amiga with two new modes, 
and passes through the graphics modes that are "native" to the 
Amiga. The two new modes, which we call HAME (nodash) and 
REG mode, appear on standard Amiga screens that pull up and 
down, go front to back, and overlay or underlay other screens in 
a 100% compatible manner. 

Developers wishing to make their applications com- 
patible with the HAM-E receive the utmost in support from Black 
Belt's technical personnel. Most applications can be supported 
with a minimum of effort on the part of the developer. Applica- 
tions that run entirely on the HAM-E will of course require more 
effort than simple output of images (such as a ray tracer might 
want to do), yet the new display modes are easy to use, and we can 
help you all through the process. 

What's the point? 

The objective of this article is threefold. First, we want 
you to know that you can work with the HAM-E display system 
easily. Next, we'd like to give you an overview of what methods 
are available, and how we might get involved with you, if you 
require assistance. Finally, we'd like to help you to understand 
how the HAM-E works. We'd like you to understand the HAM- 
E device to the extent that you may effectively consider pro- 
gramming for it in relation to projects you maybe involved with. 

Programming approaches 

Programming for the HAM-E device can be approached 
at three different levels. You can use our libraries, which are freely 
available to developers. You can use our C language source code 
as a basis for your own code. Finally, you can program to our 
specifications, which are clearly set out for you. 



The Library Interface 

One of the quickest ways to provide HAM-E support in 
your application is to use one or both of the libraries we provide. 
There is a low-level library called hame. library, and a higher- 
level library called renderhame.Iibrary. 

The low level library provides a great deal of function- 
ality, at very little cost in memory. It is a standard Amiga library, 
you simply open it and then you can call the routines contained 
there. 

Library Interface, continued... 

The routines called out in the hame. library function 
table are extremely versatile, and can form the basis for almost 
any imaginable low level manipulation of a HAME or REG mode 
screen. 

The facilities are here for building a game from scratch, 
complete with "BOB- like" routines that allow you to use the 
blatter (with complete masking) to move game objects around the 
screen. Color cycling of any number of registers allows a number 
of animation techniques without any actual data movement on 
the display. We've even provided a fast routine to move 8-bit 
buffers in fast memory into HAM-E mode screens in large chunks, 
as efficiently as possible so that youcan handle your objects in fast 
ram, and then use the library to move the object to the screen 
quickly. Once there, you can clip it with the blitter routines 
provided, and you have a complete BOB. 

If your desire is to read HAM-E mode screens, that's all 
here too. all you have to do is use the GetRGBPtxel() routine for 
each pixel in the image, and you'll have a full 24-bit readout of the 
image. 

On the other hand, if you are looking for output in one 
of the HAM-E modes, for example you might be writing support 
code for a ray-tracer, or some other application that needs to take 
it's internal RGB buffers and rum them into a HAME mode 
image, the renderhame.Iibrary is the tool you would use. This 
requires that you also open the hame.library, however you won't 
be using any of the low level tools — the renderhame.Iibrary uses 
these tools, which is why you need to open the hame.library for 
this type of operation. 
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Table of Library functions for "hame. library" 


HAME_Init ( ) 
HAME_Dispose ( ) 
HAME_SetAPen ( ) 


tells the library mode to use, basic setup function 
Frees the structure allocated by HAME_Init() 
Pick primary drawing pen (0-255) 


HAME_ReadPixel ( ) 


returns 8 bit value of pixel at x,y 


HAMEJWritePixel ( ) 


writes 8 bit value to x,y 


HAME_GetRGBPixel { ) 


returns 24 bit RGB value for pixel at x,y 


HAME_GetRG38 ( ) 


returns 24 bit color register setting 


HAME_SetRG38 ( ) 


writes 24 bit value to color register 


HAME_Ellipse() 


Draws an ellipse, filled or unfilled in "APen" 


HAME_Line ( ) 


Draws a line in "APen" 


HAME_Box ( ) 


Draws a box, filled or unfilled in "APen* 


HAME_OpenScreen ( ) 


Aid for BASIC language users 


HAME_CloseScreen ( ) 
HAME_CycleLef t ( ) 


complement to HAME_OpenScreen ( ) 
cycles the color registers 


HAME_CycleRight ( ) 


cycles the color registers 


HAME_Move ( 1 


moves the current pen position; no drawing 


HAME_Draw ( 1 


draws from the current position to x,y ________ 


HAME_8BitRender ( ) 


moves an 8 bit "byte" buffer into the HAME screen 


HAME_Scroll() 


scrolls the HAME screen 


HAME_OpenFont ( ) 


opens a standard Amiga font or a colorfont 


HAME_GetFont Palette ( > 


stuffs colorfont palette into the HAME palette 


HAME_SetFontPen ( ) 


for both colorfonts and regular fonts 


HAME_Text ( ) 


actually writes the text to the screen 


HAME_MakeFTables ( ) 


setup for HAME_QText ( ) 


HAME_QText ( ) 


very fast font rendering, more memory overhead 


HAME_CloseFont ( ) 


complement to HAME_OpenFont ( ) 


HAME_AllocClip() 


creates blank clip for your use 


HAME_GetClip() 


blits clip from screen region 


HAME_DisposeClip ( ) 


complement to HAME_AllocClip ( ) , HAME_GetClip 


HAME_PutClip() 


blits clip to screen (optional masking) 


HAME_ReadClipPixel ( ) 


returns 8 bit value at x,y in clip 


HAME_WriteClipPixel ( ) 


places 8 bit value at x,y in clip 


HAME_ReadMaskPixel ( ) 


returns 1 bit value at x,y in clip mask 


HAME_WriteMaskPixel ( ) 


places 1 bit value ay x,y in clip mask 


HAME_AllocClipMask ( ) 


creates a mask for a particular clip 


HAME_DisposeCl ipMask ( ) 


complement for AllocClipMaskf ) 


HAME_MakeClipMask ( ) 


creates mask using transparency supplied 


HAME_WaitScanLine ( } 


scan line delay to avoid flicker in games 


HAME_LockLayer ( ) 


Prevents system operations from trashing display 


HAME__UnLockLayer ( ) 


Re-allows system to render to the HAME screen 





Table of Library functions for "renderhame. library' 



HAMEJtenderHam ( ) 
HAME_RenderReg ( ) 
HAME_SaveIFF<) 



creates 18 or 24 bit output from RGB buffers 
creates 256 color output from RGB buffers 
saves resulting render as viewable IFF file 



Volume 1, Number 3 



67 



The C Code approach 

Black Belt has made availablea great deal of C language 
source code which can he used as a model for many types of 
1 1 AM-E operations. For instance, the entire source code to version 
1 .0 of our register mode paint program is on our BBS (at 406-367- 
ABBS/2227). In there, you can find routines to do almost any- 
thing, from pixel level access to blitter handling. 

C coding for the HAM-E is relatively straightforward. 
We suggest that you use our "canned " low-level routines as much 
as possible, to save yourself a great deal of coding effort. Or, if you 
feel that you could write higher performance code, you can use 
them as examples. In either case, the path to support via custom 
C code is well covered. 

Programming "to the specification'' 

The HAM-E device is fairly easy to write software for, in 
any language that allows you fast access to the Amiga's chip 
memory. 

The HAM-E uses "pairs" of four-bit, high resolution 
pixels to encode the output pixels. The Amiga maintains a high- 
resolution, four bitplane display. The HAM-E device takes pairs 
of these pixels at four bits each, and essentially turns them into 
single pixels that are eight bits each. These pixels are then used to 
load color registers, select pixel values, and so on. The Amiga 
doesn't know what's going on "behind it's back" so to speak, and 
so handles the screen as it normally would. 

REG Mode 

For REG mode, these 8 bit combination pixels are simply 
used to create an 8- bit pixel, which chooses a color register 
n Limber from zero to 255. 

HAMEMode 

For H AME mode, the 8 bit combination pixels are used 
to specify a hold-and- modify command to the display adaptor. 
We use the top two bits in the 8 bit word as 'control' bits, and the 
bottom six bits as data bits. If the top two bits are not zero, then 
the bottom six data bits are loaded into either the red, green or 
blue gun output, while the other two of the three output colors are 
'held' at the value provided by the previous pixel. 

If the two most significant bits are zero, then the bottom 
six bits are used to specify one of sixty color registers, or, to switch 
to one of three other banks of sixty color registers. If a new color 
register is chosen, then all three of the red, green and blue guns 
change to the 24-bit value that is in that color register, providing 
a "sharp edge" color change. As mentioned before, there are 60 
available. If a new bank is chosen, then all three of the red, green 
and blue guns are held through the pixel that causes the bank 
switch. This allows the image to contain up to 240, 24-bit color 
registers which can be used to change colors quite sharply, 
without fringing. 

Interlace Operation 

When the Amiga operates in Interlace mode, it's not 
really sending out a 400 line image. Instead, it's sending two 
completely separate 200 line images, which are simply placed on 
the monitor screen so that they "interleave", or interlace, with 
each other. 



The HAM-E hardware is not aware of this. It treats each 
of the 200 line images as completely separate objects, each with 
it's own set of up to 256 (or 240, in the HAME mode) color 
registers. 

As a result, you can actually have up to 512 color 
registers in a REG mode image, and up to 480 color register in a 
HAME mode image. These are divided into two sets of registers, 
one for the odd lines in the image, and one for the even lines in the 
image. 

For normal images, this really doesn't turn out to be a 
large advantage, although it can help somewhat. But there is a 
special class of images where this is really, really nice to have. 
That is, the 3-d images used by the X- Specs glasses, manufac- 
tured by Haitex. 

These glasses operate by using a Liquid Crystal Display 
technology to create a "shutter" over the entire lens on each 
eyepiece of the glasses. Then, the Amiga is made to present the 
image for one eye in the even field of the interlace i mage, whi le the 
left eye is shuttered, or blocked off. Next, the image for the other 
eye is presented in the other interlace field, while the right eye is 
shuttered. The result is that a stereo pairof images is presented to 
the user, and the HAM-E (remember the HAM-E?) can render 
these images with completely independent color registers, and 
therefore complete independence between the subject matter of 
the images. 

Conclusion 

Amiga developers who wish to join the those who are 
already supporting the HAM-E device (ASDG, Holosoft, Pro- 
gressive Peripherals, Virtual Reality Laboratories, Oxxi, and 
many, many more) have many possible levels of approach avail- 
able to them. The HAM-E provides a great deal of functionality at 
a reasonable cost to the end user, and a large number are in user's 
hands. 

If you have thoughts for library functionality that we've 
overlooked, please contact us and we'll be extremely pleased to 
listen to your ideas. If your ideas seem reasonable, we'll put them 
into the libraries as quickly as possible. 

Black Belt Systems technical support is always available 
during mountain time business hours to provide additional 
support, and we consider helping developers with their efforts in 
this matter our top technical priority. If you have questions about 
the HAM-E and developing software for it, please call our tech 
support line at (406) 367-5509 and ask for Barry or Ben. We'll be 
glad to talk to you! 



/ 



Would like like to see in-depth articles about 
programming specified pieces of equipment like the 
HAM-E. in AG's TECH? 

Let Us Know! 

Write to: 

AC's TECH Suggestions 
P.O. Box 869 

FA1I River. MA 02722-0869 
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Using RawDoFmt in Assembly 



If you have a need to print formatted strings in assembler, stop 
misting time and code rolling your own routines and read on. 



byJeffLavin 



Although the Exec library is rich in programmer- 
accessible functions, there is one extremely useful 
function that is very much under-represented in assem- 
bly language programs, particularly those written by 
beginners. This is probably because the documentation 
is confusing. If you have a need to print formatted 
strings, stop wasting time and code rolling your own 
routines and read on. 

RawDoFmt(), pronounced "raw do format", is 
used in a number of Exec's higher functions including 
KPrintfQ, found in the debug. lib, DPrintf(), found in the 
ddebug.lib, and of course ROMWack, the system 
debugger. It is capable of handling most standard 'C 
type formatting with the exception of floating point. 
RawDoFmtQ packs an amazing amount of functionality 
into less than 600 bytes. All of the following 'C type 
formatting is supported: 



M - print an inl 

*c - print a character 

1« - print an unsigned hexadecimal integer 

%s - print a string 



Additionally, the following modifiers are supported: 

Justification: *-d - print an integer left-justified 
Lead char select: *08d - fill leading space w/zeros instead cf blanks 
Field width: 48d - print an integer in a field S spaces wide. 
Field truncate: »8.4d - only print 1st 4 chars of integer 

in a field 8 spaces wide. 
Data size: Hd - print a long integer. 

Integers are used here as examples, but these modifiers 
work with other data types as well. With the exception 
of the modifiers for size and for leading zeros/blanks, 
they also work with strings. 



The register usage for RawDoFmtQ is: 

RawDoFmt (FormatStr. DataStream, PutChProc, 

a: a2 

where: 

FormatStr = Pointer to 'C language type null-termi- 
nated format string. 

DataStream = A stream of data that is interpreted 
according to the format string. Defaults to WORD size. 
BYTE size data is not supported. Pointers to strings are 
always LONG. Also note that the data must match the 
sizes called for in the FormatStr. 

PutChProc = The user-supplred procedure Called with each char output. 

For example: 



PutChProc (Char, PutChData) 
D0:B A3 



PutChData = An address register passed through to 
PutChProc(). This is generally used as a pointer to a 
character buffer, which must be big enough to hold any 
possible formatted string. 

If you find this confusing, you're in good company! 
Basically, to use RawDoFmtQ, you need to do the 
following: 



Volume 1, Number 3 



69 



lea (DataStream.pci.al 
movea.l al,a2 
move.w d0,(a21* 
move.l dl,(a2|+ 
move.w *19020, (a2)t 
lea (SomeString,pc],aQ 
move.! aO, (a2) 
lea I fmtstring. pcl.aO 
lea (PutChProc, pel ,a2 
lea (CharB-af,pc),a3 
novea.l (AbsExecaase}.w,a6 
jsr (_LVORawDoFmt,a6) 



;Ptr to Data 

,-Data: An Int 
;Data: A Long 
;Data: toother Int 
;Data: A ptr to a string 

;Fti to FomatStr 

; Routine to do whatever you want 

;Buffer for use by PutChProc 

;£xec library hase 

,-Cail the routine 



fmtstring db 



'lot: Id, Long: lid, Hexlnt; Sid. String; 



The data could be passed on the stack instead, like so: 



pea (SomeString.pc) 
move.w 119020, -(spl 
move.l dl,-(ap) 
move.w d0,-(sp) 
movea.l sp,al 



Push a ptr to 3 string 

Push another Int 

Push a Long 

Push an Int 

Get DataStream ptr into proper 

register 



Remember that data pushed on the stack is accessed in 
reverse order! 

Then, when you return from RawDoFmtQ: 



Lea (SC,sp),sp 



Fix stack before ret 



There are a number of things you can do with the 
PutChProcQ function. In this example we are writing 
each character to stdout as we get it: 



PutChProc movem.l d2-d3/a6, - lap) 
move.b dO, (a3) 
move.l Lstdoutl.dl 
move.l a3,d2 
moveq il,d3 
movea.l l_DosBase> ,a6 
jsr l_LV0Write,a6) 
movem.l Isp)+,d2-d3/a6 
rts 



;Save st ; r ' 

;Put char in buffer 

;Filehandle previously opened 

;Suffer 

; Length 

;Dos library base 

;Write the char to stdout 



The problem with this example is that single character 1/ 
O takes a tremendous amount of overhead for each 
character. Here's a better way: 



HyFormat movem.l d7/a2-a3/a6,-(spl 

lea IDataStream.pc] ,al 

lea (SomeString.pci ,aG 

move.l aO.lal) 

lea (fmtString, pc), aO 

lea ( PutChProc, pc) , a2 

lea ICharBuf,pe),a3 

novea.l (AbsExec3asel.v,a6 

moveq »0,d7 

jsr (_LVORawDoFmt,a6) 

move.] 07, dO 

subq.l #i,d0 

movem.l Ispl*,d7/a2-a3/a6 
rts 



PutChProc 



move.b 
addq.l 
rts 



Ia3|* 

Si,d7 



;Save stuff 

;Ptr to Data 

;A ptr to a string 

;Ptr to FormatStr 
;Char fill procedure 
,-Buffer for use by PutChProc 
;Exec library base 
; Clear character count 
,-Call the routine 

,-Count of characters, excluding null 



;Put character in buffer 

:Add 1 to character count 



fmtstring db 
SomeString db 



'Kary had a little Ianb ls',0 
'whose fleece was white as snow.',0 



When this subroutine returns, the character count will 
be in DO. If there were no characters output, DO will 
contain -1. You can test both of these by checking the 
flags: 



bsr MyFcrmat 
bpl.b GotSomeChars 



; Branch on or greater 
;Got no characters 



As stated before, just as with C's printfQ, you cannot pass 
bytes to RawDoFmt(). In order to print a byte size or 
character data, you must pass it as a word: 



or 



moveq »C,dO 
move.b #27, dO 
move.w dO, (all 



clr.w (al) 
move.b I'a", (!,al) 



;A1 is pointing to DataStream 
;A1 is pointing to DataStream 



In addition to not being able to pass characters as bytes, 
you can't pass the percent sign (%) in a format string at 
all! You can't use '%%' here to get a single %, the way 
you can in printf(). So how do you print a single percent 
sign? Easy: 



'■■ >roc 



: -.■:•.: 

rts 



>3)4 



When you return from RawDoFmt(), find the length of 
the buffer and write it all out at once. Output from 
RawDoFmtQ is always null terminated. 

Several more points, and on to the real code. D7 is the 
only register besides A3 that RawDoFmtf) doesn't save, 
and also passes on to PutChProcQ. If you want a count of 
the characters PutChProc() puts into your buffer, with- 
out doing a strlenQ when it returns, you need to do the 
following: 



move.w #97, (all 

moveq 10, dO 

move.b ("I',d0 

move.w d0,l2,all 



,-Ke fervently hope & pray! 



fmtstring db 



;A1 is pointing to DataStream 
'AG's Tech readers .■.;-: liked this article is Id .'. 



Finally, because RawDoFmt() is only capable of printing 
unsigned integers, you might think there would be a 
problem if you needed to print signed numbers. Here's 
one way: 
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SignedWord 



.notneg 



lea 

tst.w 

bpl.b 

lea 

neg.w 

lea 

move.w 

bsr.w 



Pos . fmt 



:: 



(Fos.fmt.pcl.aO 

dO 

. no tneg 

(Neg.fmt,pc),aO 

dO 

(_FmcArgs-DT, a5) , al 

do, (al) 

Printf 



'-*-d',0 



Default to positive 

Check our WORD size data 

Branch if positive 

OK, get negative fonrat string 

Hake number positive 

Ptr to DataStream 

Stick our data there 

Print it (see routine below) 



; Positive format string 
jNegative fonrat string 



Because the sign bit is the MSB in our data, separate 
routines must be written to handle BYTES, WORDS, or 
LONGS. This example above only works on WORDS. 

Following is an entire library of 'C type formatting 
routines for assembly language programmers: 



> ******** ********* 



NAME: 

FUNCTION: 

INPUTS: 



r™ -.: 



SPrintfO 

Print formatted strings to a buffer. 

AO = Format string. 

Al = Ptr to arguments, 

A2 = Ptr to buffer (preservedl . 

None 

E0-D1/A0-A1 



(©J Memory 
Management, Inc. 

Amiga Service 
Specialists 

Over four years experience! 

Commodore authorized full 

service center. Low flat rate plus 

parts. Complete in-shop inventory 

Memory Management, Inc. 

396 Washington Street 

Wellesley,MA0218l 

(617) 237 6846 



Circle 186 on Header Service card. 



SPrintf 


movent. 1 a2-a3/a6,-(sp) 


;Save stuff 


Printf 


movem.l a2-a3/a6,-(sp| 


rSave stuff 




movea .1 a2 , a3 


i Buffer 




lea ( PutChProc, pc),a2 


;Byte fill routine 




lea [PutChProc, pc),a2 


,'Char fill procedure 




lea (Buffer), a3 


;Ptr to your buffer 




movea. 1 (AbsExecBase). w,a6 






movea. 1 (AbsExecBase) .w,a6 






jsr ILVORawDoFmt.aS) 


;Do it: 




jsr (_LVORawDoFmt,a6) 


;D0 it! 




movem.l Isp)*,a2-a3/a6 






movea. 1 al.aO 






rts 






bsr.b Puts 

movari.l (sp)+,a2-a3/a6 




PutChProc 


move.b dO, U3) + 


;Char fill procedure 




rts 






rts 




*****•«••******.*»»***•♦*.**«***************************•**** 


••.**.+•+• 


•••** ............*.... 





* NAME: 


Puts II 




■ :::j.;.: 


FPrintf U 




* FUNCTION 


Writes a message to stdout. 




• pusction 


Print formatted strings to a 


specified file. 


* INPUTS: 


AO = Ptr to message. 




■ :::::.. : 


AD = Format string. 




* RETURN: 


None 




* 


Al = Ptr to arguments. 




* SCRATCH: 


D0-D1/A0-A1 




* 


DO = FileHandle. 




.......... 


************** ..+**+**+***.** 


.........a*.*.*.***** 


■ =::. .•■■:: 


Hone 










* SCRATCH: 


D0-D1M0-M 




Puts 


movem.l d2-d4/a6,- (sp) 
move.l (_stdout),d4 
bsr.b WriteHsg 


;Save stuff 

; stdout already open 


FPrintf 


movem.l d2-d4/a2-a3/a6,-(spl 


;Save stuff 




movem.l (spl+,d2-d4;a6 






move.l d0,d4 


; Fi leKandle 




rts 






lea (PutChProc, pc),a2 


;Byte fill routine 










lea (Buffer], a3 


,-Ptr to your buffer 


********** 


.,......*,,...........,.*»*.. 


................*<*** 



movea, 1 (AbsExecBase). w,a6 

jsr (_LV0RawDoFmt,a6) ;Do it! 

movea.! a3,a0 

bsr.b WriteHsg 

movem.l Isp)-,d2-d4/a2-a3/a6 

rts 



* NAME: 

« FUNCTION: 

* ::: : ■". ': 

* RETURN: 

* SCRATCH: 



FPutsO 

Writes a message to a specified file. 

AO s Ptr to message. 

CO = FileHandle. 

None 

D0-D1/AO-A1 



FPuts moveu.l d2-d4/a6,- Isp) 

move.l d0,d4 

bsr.b WriteHsg 

movem.l (sp]*,d2-d4/a6 
rts 



:Save stuff 
i FileHandle 



■ :;.-:■:: : 

1 FUNCTION: 
1 INPUTS: 

' RETURN: 
' SCRATCH: 



Printf I) 

Print formatted strings to stdout. 

AO = Format string. 

Al = Ptr to arguments. 

None 

00-D1/AQ-M 



* NAME: WriteHsgO 

* FUNCTION: Connon subroutine used by FPrintf, FPuts, Printf, and Puts. 

* INPUTS: AO = Ptr to message. 

W = FileHandle. 
« RETURN: None 

* SCRATCH: D0-D1/A0-A1 



*i.»********.*.+ 



;-;:ii-:: : : 


move . 1 


a0,d3 




;How long i. 


IS 


tst.b 

bne.s 

exg 

sub.l 


(a0)4 

IS 

a0,d3 

a0,d3 








.-, ::.;;.. 


Il,d3 




; Length 




move.l 


a0,d2 




,-Buffer 




_".3. 


d4,dl 




,- Fi leHandle 




:v=i.l 


1 DosBase) 


a6 






]sr 


. . :v.ri;s 


a5) 






r-.s 









Note: All code used in this article is written in new 
M68000 family syntax. The new syntax was developed 
by Motorola specifically to support the addressing 
capabilities of the new generation of CPUs. 
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re you a freelance Amiga Artist? 



...Programmer? 
...Musician? 
...Project Manager? 
...Toolsmith? 
...Writer? 

...Multimedia Consultant? 
...Video Consultant? 
...or any other Amiga specific 
freelance professional? 



We are compiling a directory of international Amiga freelance talent! You get maximum exposure with 
your FREE listing! We want to hear from you! 

In 200-250 words, describe your unique talents and services. You should also include a small list of recent 
projects. 

Be sure to include your full name, company name (if applicable), full address, and phone/FAX numbers. 

Also, list any appropriate E-Mail addresses. 

Send your information to: 

PiM Publications, Inc. 

Amiga Freelancers Directory 

Attn: Listings 

P.O. Box 869 

Fall River, MA 02722-0869 

or FAX 1-508-675-6002 



For more information call 1-508-678-4200 



WildStar 

Discovering an AmigaDOS 2.0 Hidden Feature 



by Bruno Costa 



If you are a part-time MS-DOS or UNIX user, you have 
certainly typed a * instead of the AmigaDOS#? wildcard in your 
Amiga shell. Unless you were an ARP (AmigaDOS Resource 
Project) user you would have been prompted with something 
like "*.c object not found". If you, like me, upgraded to Work- 
bench 2.0, you were forced to drop ARP usage to benefit from the 
new and really improved operating system. This time there was 
no way out: you would really need to learn using the "#?" 
wildcard. And that is what you did — or at least what you tried 
to do. But (here is the but you were waiting for!) there is a solution, 
a solution already implemented by Commodore programmers 
that is hiding quietly, deep into AmigaDOS 2.0. 

The solution to this wildcard compatibility problem was so 
simple, I was not surprised to see it working in less than five 
minutes (it was meant to be either a complete success or a 
complete failure). It involved simply the change of one single bit 
in the AmigaDOS root node — a global structure that holds some 
AmigaDOS system-wide variables. Studying the new include 
files provided for Workbench 2.0 programming, I noticed that the 
RootNode structure had, among others, a new field called rn_Flags 
which had only one bit with a defined meaning. This bit was 
defined by the symbolic name RNB_WILDSTAR— it surely meant 
either what I wanted it to be, or something really wild! I wrote a 
simple program to toggle this bit on, and after compiling, quickly 
typed a "dir *.c" to see that a new era in my Amiga Workbench 2.0 
usage had begun. 

Note that this feature was, to my knowledge, completely 
undocumented. It was not mentioned in my early version Work- 
bench 2.0 "Using the System Software" manual or in any of the 
other manuals that came withmy Amiga 3000. Even further, the 
bit definitions present in the include files didn't have any ac- 
companying comments. Under such circumstances I don't have 
any explanations why this feature is not turned on by default 
(maybe a persisting bug ?), or why there isn't something like an 



environment variable that could be set to 1 or to turn the feature 
on or off. I have been using this little command in my startup- 
sequence since the moment I discovered it worked. There is only 
one minor nuisance: when used alone in a pattern, such as in 
"copy * to ram:", the star will not mean what you would expect 
(copy all files in current directory to ram:), instead it will mean the 
current shell window (as it did when used under WB 1.3 or a 
default WB 2.0). Apart from that, 1 think this is a very welcome 
compatibility enhancement that works with all the AmigaDOS 
2.0 commands that accept patterns. 

/* 

* wlidstar.c - toggles the star as a wildcard in AmigaDOS 

- Bruno Costa - 29 Jan 91 - 29 Jar. 91 
■ (Compile with lc -L wildotar.c) 

^include <exec/types.h> 

ttinclude <cl:b/dos_protos .h* 

It include <pragmas/dos_pragnas,h> 

exterr. struct DosLibrary "DOSBase; 

Rdefir.e print (msg) Write lOutputO, isvsg, sizeof (msg!) 

void _nain [void! 
( 
struct RootNode *root = DOSBase->dl_Root; 

if |D0SSa5e->dl_iib.lib_Version < 3d) 

prir.t ('Sorry, this program needs WB 2.0.\n"J; 
else 



( 



' ..rn.Flags *= RNF_KILDSTAR,- 

if lrOOt-srn_Flags k RNF_KILDSTAfi) 

print i'The star is now a wildcard. \u") ; 

else 

print "Trie star is now a nonral character. \n* } ," 
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SYSTEM CONFIGURATION TIPS 
FOR SAS/C-ON DISK! 



by Paul Castonguay 



Last issue you saw three different installations of SAS/C for a 
two floppy Amiga, each one differing in how it used system 
resources to give you an environment in which you could 
write, compile, and execute programs written in C. Even a 
512K system proved to be a very powerful C development 
workstation, In this document I will discuss those installations 
in detail. 

BACKGROUND MATERIAL (Skip if you like) 
DEVICE NAMES 

A device name in AmigaDOS is any legal name whose last 
character is a colon. The name dfl: is a device name and it 
represents a physical accessory connected to your computer, 
the external floppy drive. Thus dfl: is an example of a PHYSI- 
CAL DEVICE NAME. 

But the Amiga also has the ability to recognize other 
things through the use of device names. The easiest to under- 
stand is the volume name of a diskette. Suppose you have a 
diskette whose volume name is My_Work and it is mounted in 
dfl:. To see what is on that diskette you could enter: 

Dir dfl; 
or 

Dir Myjv'ork: 

The second way refers to the diskette not by the physical 
device in which it is mounted, but by its volume name. That is 
an example of a LOGICAL DEVICE NAME. 

Perhaps you are thinking that My_Work: should be called 
a physical device name because a floppy diskette is something 
physical, something that you can touch. Yes you can touch a 
diskette, but you can't physically touch its volume name. In 
fact, that name can easily be changed by using the "Rename" 
item on the "Workbench" menu. Renaming a diskette is an 
operation performed by the Workbench program, and a 
program at its most basic level is nothing more than a series of 
logical operations inside the computer's central processing 
unit. Thus the volume name of a diskette is a logical property, 
not a physical one, and since adding a colon on the end makes 
it also a device name, we get a "logical device name". If you 
use the volume name without the colon the computer does not 
recognize it as a device but looks instead for a file or directory 
of that name within your current working directory. 



AmigaDOS stretches the concept of devices even further 
by allowing you to define a logical device name for any 
directory in your disk filing system. To do that you use the 
Assign command. Suppose in my previous example the 
diskette My_Work had two directories on it, C_Programs and 
BASIC_Programs. You could assign device names to each, like 
this: 



Assign My_C: My_Work:C_Progr6ms 
Assign M^B: My_Work:BASlc_Programs 

Now you can refer to these directories conveniently by their 
device names rather than their longer path names. The 
command: 



Dir My_C: 

produces a report of the files stored in the directory 
My_Work:C_Programs. Again, the last character of a logical 
device name must always be a colon. 

The Assign command uses the following format: 

Assign <device name> <directory name> 

To see a report of the logical devices (as well as the physical 
ones) that are currently defined on your system enter the 
Assign command with no argument. Here is that report on my 
system: 

Vc ' ires : 

Hyjfork [Mounted 1 
RAH DISK [Mounted] 
RAD [Mounted] 
Workbench [Mounted] 



Directories: 

My_C 

My_B 

FCWTS 

S 

CLIPS 

t:: 



Hy_Work : C_Programs 

Hy_Work : HASIC_Programs 

Workbench: Fonts 

RAH DISX:S 

RAM DISK:clipboards 

RAH DISKrenv 
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: 




RAM DISK:t 


L 




Volume: Workbench 


c 




Volume: Workbench 


DEVS 




Volume: Workbench 


LIBS 




Volume: Workbench 


SYS 




Volume: Workbench 


Devices : 






PIPE AUX 


SPEAK HEWCGN DF1 


FRT PAR SER RAW CON 


RAH DFO RAD 





The report is divided into three sections: Volumes, Directories, 
and Devices. "Volumes" represent the names of the diskettes 
that are presently recognized by the system. They correspond 
to the disk icons appearing on the Workbench screen. "Directo- 
ries" represent the logical device names that have been 
assigned to various directories in the disk filing system. You 
can see My_C: and My_B: at the top of the list. "Devices" 
represent physical devices attached to the system, printers, 
disk drives, and stuff like that. 

TWO KINDS OF LOGICAL DEVICES 

There are two different kinds of logical devices in the group 
called "Directories". The first is called "User Logical Device". 
My_C: and My_B: are examples of that. They were assigned by 
me, the user, for my own purposes. The other is called "System 
Logical Device". These are special reserved device names that 
have specific meaning to the computer. They are assigned 
automatically during boot-up. To be able to configure your 
Amiga yourself you must understand the purpose of at least 
four of these System Logical Devices. 

C: DEVICE - COMMAND DIRECTORY 

This is the System Logical Device in which all AmigaDOS 
commands are stored. On a generic Workbench diskette it is 
assigned to the Workbench^ directory. Whenever you enter an 
AmigaDOS command the system looks for it in the C: device, 
also called the command directory. If there is no program of 
the name you entered the computer responds with "Unknown 
Command". 

S: DEVICE ■ SCRIPT DIRECTORY 

This is the System Logical Device in which all script files are 
stored. Script files are text files containing AmigaDOS com- 
mands. The most important of these are the Startup-Sequence, 
StartupII, and Shell-Startup files that get executed automati- 
cally at boot-up time. 

FONTS: DEVICE - FONTS DIRECTORY 

This is the System Logical Device in which the Amiga's disk 
based fonts (fancy looking letters) are located. They have 
names like Diamond, Emerald, Sapphire, ... etc. They can be 
used to give your programs a more professional appearance. In 
this series of articles we will study how to access these fonts 
from our C language programs. 



SYS: DEVICE ■ THE SYSTEM DIRECTORY 

This System Logical Device serves the same purpose as the 
volume name on your boot-up disk. The computer needs to 
refer to the boot-up diskette often for its general operation, but 
that volume name can be changed by you. It therefore uses its 
own name, the logical device name SYS:, which is assigned 
automatically at boot-up time. 

There are other System Logical Devices that are important 
for the computer's operation but I will not be doing anything 
with them in my discussion of system configuration. You can 
learn about them by reading any AmigaDOS reference book. 

RE-ASSIGNING SYSTEM DEVICES 

The most powerful feature of system devices is their ability to 
be re-assigned by the user. You can try this out yourself from a 
SHELL window. Enter the command: 

Assign Fonts: RAM: 
Then enter: 



Assign 

You now see that the Fonts: device points to the RAM disk. 
That means that software wanting to use the Amiga's disk 
based fonts will look for them at that location. But there is one 
problem, there are no fonts in the RAM disk. If you try now to 
run such software it won't be able to find them. You had better 
change it back. 

Assign Fonts: SYS:Fonts 

MAKING ROOM ON A WORKBENCH DISKETTE 

I am often asked by beginners how to make extra room on a 
boot-up (Workbench) diskette. The usual reason for wanting to 
do that is to be able to run certain software without having to 
perform a multitude of disk swaps. In our case we want to use 
the SAS/C compiler and we do not want to have to flip 
diskettes every time we compile a program, At the same time 
we do not want to loose any important features that come on a 
standard Commodore Workbench diskette. 

You should never just blindly delete things off your 
Workbench diskette. Often what you delete is important for 
the operation of your computer. Days or weeks later you may 
find that certain programs, or indeed certain features of certain 
programs, no longer work properly. By that time you will have 
forgotten what files you have deleted. What a mess! 

SYSTEM RESOURCES ON TWO DISKETTES 

A better approach is to distribute your Amiga's resources over 
two diskettes in such a way that the most frequently used ones 
are conveniently located on the boot-up one, while the rest are 
transferred to the other. You might call this second diskette 
"Workbench_2". But that's not all you should do. You should 
also make sure that the system knows where to find those 
transferred resources when it needs to use them, 
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For example, you might think that the fonts directory is 
not important enough to keep on your boot-up diskette. I 
agree. But if you blindly delete all the fonts they will no longer 
be available for software that needs to use them. Worse, you 
yourself will not be able to access them from within your C 
programs. A better approach would be to transfer your fonts to 
a second diskette and to inform the system where it can find 
them by assigning the FONTS: device to that location. By 
doing that you will both save room on your boot-up diskette, 
and still be able to use the Amiga's disk based fonts. When you 
run a program that needs to use them the system will ask you 



to: 



'Insert Workbench^ " in any drive" 



After your program reads whatever font it needs, you will be 
able to remove Workbench_2 and re-insert another diskette for 
the remainder of time that you use the program. Often the font 
will remain on the system after your program has terminated, 
allowing you to run the program again without having to re- 
insert the Workbench_2 diskette, 

STEP BY STEP PROCEDURE 
TO MOVE FONT DIRECTORY 

To make sure you understand exactly what I am suggesting, 
let's work together and modify a standard (generic) work- 
bench diskette to use a font directory located on a separate 
diskette. To perform this experiment you will need one blank 
diskette and one unmodified copy of Commodore's Work- 
bench. 



Step 1 

Boot-up using a generic Commodore Workbench in dfO: and a 
blank diskette in dfl: 

Step 2 

Format (Initialize) the diskette in dfl: calling it Workbench^. 

Step 3 

Open a SHELL window and enter the following commands: 



HakeDir dfl:Foncs 

Copy Fonts: to dfl:Fonts all 

Delete Fonts:*? all 

Step 4 

Enter the following command: 

3a S: Startup-Sequence 

This opens the ED editor with the Startup-Sequence file. 



Step 5 

Using the [DOWN-ARROW] key move the cursor towards the 
end of the file and insert the following new line immediately 
before the LoadWB command; 

Assign FONTS: (torkbenchJJ : Fonts 

Step 6 

Press the [ESC] key followed by X and [RETURN]. This saves 

the file. Wait for all disk activity to stop. 

Step 7 

Re-boot and confirm that the system font device is now 
pointing to the Fonts directory on WorkBench_2 (use Assign 
command in the SHELL window), Also verify that your 
workbench diskette is now only 85% full (use the Info com- 
mand in the SHELL window). Try using the fonts by executing 
the NotePad program and confirm that they are loaded from 
the Workbench_2 diskette. 

Thus you have created room on your boot-up diskette 
without loosing the ability to use the Amiga's disk based fonts. 
When you boot up with this modified workbench the system 
will ask you to insert the Workbench_2 diskette in order that it 
can assign the FONTS: device to the correct directory. Insert it 
in dfl: After boot up you can remove it. You will not need it 
until you run a program that uses the FONTS: device. 

That completes the experiment. 

There is an added advantage to transferring the disk based 
fonts to a second diskette. You now have enough room to 
combine with them the extra fonts that come on the "Extras 
1.3" diskette, Courier, Helvetica, and Times. That will give vou 
ten different fonts to use in your programs. 

REMOVING COMMANDS FROM C: DEVICE 

An often used trick to make room on a boot-up diskette is to 
remove Amiga DOS commands from the command directory. 
Again, if you are not careful you can get yourself into trouble, 
especially if you have little knowledge about what it is you are 
removing. Instead of just deleting commands you should 
transfer them to a second diskette and inform the system 
where it can find them in the event that they are needed, just 
like you did for the fonts. But in this case you will not be able 
to re-assign the C: device to Workbench_2. It must remain 
assigned to SYS:c where your most frequently used 
AmigaDOS commands are kept. Therefore, in order to inform 
the system of the location of transferred AmigaDOS com- 
mands, you will need to use a new concept. 

SHELL ALIAS 

Alias is a SHELL feature that allows you to redefine the names 
of commands and programs on your system. For example, 
suppose you are an experienced IBM-PC user and you want to 
use the word "Erase" in place of the AmigaDOS Delete 
command for removing files from your disks. You could 
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simply rename the Delete program in the command directory 
from Delete to Erase, but I don't suggest you do that. Someone 
else using your computer would not be able to figure it out. 
Besides, as you use your Amiga more and more, and your IBM 
less and less, vou may find yourself wanting to use Delete 
instead of Erase. Another suggestion might be to make an extra 
copy of the Delete program in the command directory and call 
it Erase. That would work but it would also waste valuable 
disk space. What you really need here is a way to make both 
commands work on the same program and that is where the 
Alias feature comes in. It allows \ ou to use a new name for an 
already existing command. Enter into a SHELL window: 

Alias Erase Delete 

The above Alias allows you to enter the command Erase and 
the computer will substitute in its place the command Delete. 
At the same time the command Delete still works normally. 
You can get a report of the alias definitions that are in effect on 
your system by entering the command Alias with no argu- 
ment: 



Alias 



L 




D 



™ DATA 
ACQUISITION 

SYSTEM 
FOR AMIGA 




g^M MODULE 



LOW COST SYSTEM FOR MONITORING EVENTS 
WITH YOUR AMIGA MEASURE, GRAPHICALLY 
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POWER SUPPLY REQUIRED- CONNECTS TO SEC- 
OND GAMEPORT DOES NOT INTERFERE Wl TH 
PARALLEL OR SERIAL PORT OPERATION 
MULT 1 TASK I NG SOFTWARE RUNS FROM WORK - 
BENCH COMPLETE HARDWARE AND SOFTWARE 
SYSTEMS STARTING AT $791° THIS PRODUCT 
SHOWS THE TRUE POWER OF THE AMIGA 



BOONE TECHNOLOGIES 

P BOX 15052, RICHMOND, VA 23227 
WR I TE F OR 1 NFORMA T I ON AND DEMO D I SK 



Circle 183 on Reader Service card. 



Unfortunately, the above Alias definition is effective only in 
your current SHELL window. If you open up another by 
double clicking on the SHELL icon you will find that the Erase 
command is unknown in that window. But there is a simple 
solution. You put your alias definitions in the file called "Shell- 
Startup". By doing that they will get established automatically 
at boot-up time and will be effective in every new SHELL 
window that you open. 

ALIAS NAMES FOR COMMANDS 
ON WORKBENCH J DISKETTE 

It is possible to transfer certain commands from your com- 
mand directory to the Workbench_2 diskette and to inform the 
system of their new location by giving them alias names. Using 
the same diskettes from our earlier font experiment, enter into 
the SHELL window: 

MakeDir Workbench_2:c 
Copy C:Ed to Workbench_2:c 
Delete C:Ed 

That copies the Ed editor to Workbench_2 and deletes it from 
the command directory. If you now try to use it by entering: 

Ed test.txt 

it will not work. But, if you enter the following command: 

Alias Ed Workbench_2:c/Ed 

And try again: 

Ed test.txt 



The system picks up the program from the Workbench_2 
diskette. 

Press [ESC], then Q, then [RETURN] to leave the editor. Note 
that if the Workbench J2 diskette is not physically mounted 
when you enter the above command the system will ask you 
to: 

"Insert Workbench^! in any drive" 

So now you see that you can transfer commands from your 
command directory to another diskette and not loose the 
ability to use them. You do that by defining alias names that 
specify their entire path at the new location. 

SMALL PROBLEMS WITH ALIAS 

An alias works fine when you enter commands from a SHELL 
window, but not when you use the older CLI. You see, Alias is 
not an AmigaDOS command but a feature of the SHELL 
window, available only on version 1.3 of the Workbench. Thus 
to use this technique you will have to upgrade to AmigaDOS 
1.3. 

In addition alias names will not be recognized by the 
IconX program (running a script from an icon), although they 
will work fine if you execute that same script from a SHELL 
window. It turns out that this is a minor restriction because 
someone who runs scripts from icons usually has enough 
system memory to make those commands memory resident 
anyway, removing the problem. I will present the concept of 
making commands memory resident in a few minutes. 
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PRACTICE USING ALIAS NAMES 

Since there is lots of room on the Workbench_2 diskette and 
since you will want to experiment a bit deleting different 
commands, why don't you copy your entire command 
directory to Workbench_2. Enter the following command: 



You can do the same thing with the AddBuffers com- 
mand. Again you must change your Startup-Sequence from: 



Addbuffers dfO: 30 
Addbuffers dfl: 30 



Copy C: to Workbench_2 : c 

That way you won't have to bother making sure that you have 
previously copied commands to Workbench_2:c before 
deleting them from the command directory. They will all be 
there already. 

There are two commands that you can safely delete from 
your command directory and transfer to WorkbenchJ2, Ed and 
Edit. You can also transfer DiskChange and Lock if you do not 
have a 5 1/4 inch disk drive unit or a hard drive on your 
system. Simply add an alias definition in each case to the Shell- 
Startup file. 

Alias Ed Workbench_2:c/Ed 

Alias Edit Workbench_2:c/Edit 

Alias DiskChange Workbench_2:c/DiskChange 

Alias Lock Workbench^ :c /Lock 

You can do the same with a number of other commands except 
that you may also have to modify the Startup-Sequence file as 
well (the file in the S: device that gets executed when you boot- 
up). Note that the Startup-Sequence file executes from a 
version 1.2 CLI command window, not a SHELL window, and 
as a result it does not recognize alias names. The solution is to 
modify the Startup-Sequence file to include the entire path 
name of any commands that have been transferred to the 
Workbench_2 diskette. 

A good example of this is the SetPatch command. This 
command is used only once, during boot up. Thus there is little 
reason to leave it on your boot-up diskette. Delete it from your 
command directory and change the first line of your Startup- 
Sequence from: 

SetPanch >NIL: ,-pacch system functions 



to: 



Workbench_2:c/SetPatch >NIL: ;patch system functions 

For future reference you should also define an alias for it in the 
Shell-Startup file. 

Alias SetPatch Koricbench_2:c/Sec?atch 

Thus you have deleted a command from the command 
directory, transferred it to Workbench^*, and told the system 
where it can be located if needed in the future. Incidentally, if 
you have 1 Megabyte of chip ram on your system you should 
use the "r" argument in the above SetPatch command. 



to 



Workbench_2:c/Addbuffers dfO: 30 
Workbench_2:c/.Addbuffers dfl: 30 



Then add an alias definition in the Shell-Startup file. 

Alias Addbuffers W"orkbench_2:c/Addbufiers 
Are you getting the idea? 



ONE MORE WAY TO SAVE DISKSPACE FROM C: DEVICE 
Yes, I still have another trick up my sleeve. However this one 
is only for owners of IMeg or larger Amiga's because it uses 
up valuable system memory. 

As you know AmigaDOS commands are stored in the C: 
device on the Workbench disk. Every time you use one the 
system must first load its corresponding program from the C: 
device on the floppy diskette in order that it can be executed. 
This makes the Amiga seem slow and sluggish compared to 
other computers. But that's not the way the Amiga was 
intended to be used. Instead, depending on how much 
memory you have available, you should transfer your most 
frequently used commands to system memory where they will 
execute instantly. Enter: 

Resident C:Dir 

From that point on whenever you enter the Dir command the 
system will use the version in system memory, not the one on 
the Workbench disk. In fact, the Workbench diskette no longer 
needs to be physically mounted in dfO: for the Dir command to 

work. 

To see a report of the commands currently resident in memory 
on your system enter the Resident command with no argu- 
ment: 

Resident 

Here are the ones currently defined on my 2Meg system: 
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Type 
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As you can see, I use quite a few. 

To automatically make AmigaDOS commands memory 
resident at boot- up time you must place instructions in the 
StartupII file, not the Startup-Sequence. 

If you make a command memory resident it makes sense that 
you no longer need to keep a copy of it in your C; device. 
Remember however that if a command is deleted from C: the 
resident command in the StartupII file must refer to it by its 
complete path name, like this: 

Resident Workbench_2:c/Dir 

Thus the Dir command gets loaded into executable memory 
directly from the Workbench_2 diskette at boot-up time and no 
longer needs to be kept in the C: device. 

In addition you must realize that during boot-up the Startup- 
Sequence file knows nothing about these resident commands. 
This is a similar problem to the one described above where the 
Startup-Sequence did not recognize alias names. The solution 
is the same, modify the Startup-Sequence file to include the 
complete path name of any command that it uses from the 
Workbench„2 disk. 

A good example is the Echo command. Suppose you delete it 
from your command directory. The resident command in the 
StartupII file must specify: 

Resident Workbench_2:c/Echo 




Original Feature*: 

• Enhanced, compiled BASIC 

• Extensive control structures 

• True Recursion 
& Subprograms 

• FAST Real Computations 

• Easy To Use For Beginners 

• Can't Be Outgrown 
By Experts 



Version 2.0 Added: Version 3.0 Added: 



• Animation & Icons 

• IFF Picture Reader 

• Random Access Files 

• F-Bassc linker 

• Improved Graphics 
& Sound 

• RECORD Structures 
Pointers 



• Integrated Editor 
Environment 

' 020/030 Support 

• IFF Sound Player 

' Built In Complex/Matrices 

• Object Oriented Programs 

• Compatible with 500, 1000, 
2000, 2500, or 3000 



F-BASIC™Wifh User's Manual & Sample Programs Disk 
-Only $99.95- 

F-BASIC With Complete Source Level DeBugger 

-Only $159.95- 



F-BASIC Available Only From: 

DELPHI NOETIC SYSTEMS, INC. 

Post Office Box 7722 
Rapid Cily. SD 57709-7722 

Send Cheek Of Money Older 01 Wjite For Into 
Credil Curd or CO D Call {60S) 348-0791 



Circle 199 en Reader Service card. 

Summary 

I have presented three ways of making extra room on your 
boot-up diskette without losing any of the features normally 
available on a Commodore Workbench diskette: 

1. Transfer a system logical device to a second diskette and 
re-assign that device to let the system know its new 
location. 

2. Transfer AmigaDOS commands to a second diskette and 
use alias names to let the system know their new 
location. 

3. Transfer AmigaDOS commands to a second diskette and 
make them memory resident by loading them directly 
from their new location. 



and the Startup-Sequence file which uses the Echo command 
must use its full path name: 



More information on the installation o/SAS/C is contained on the 
enclosed disk. 



Workbench_2:c/Echo "Amiga Workbench Disk. Release 1.3.2 version 34.28" 



/ 
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Hash for the Masses 



An Introduction to Hash Tables 



by Peter Dill 



Nicholas Wirth, creator of the computer languages 
Pascal and Modula-2, titled one his books on programming 
Data Structures + Algorithms = Programs. Surely this title is one 
of tantalizing simplicity for someone trying to decompose a 
programming problem into these manageable units. There is a 
definite interplay between algorithms and data structures — 
some algorithms place heavy emphasis on rapid data inser- 
tions and queries, while for others it is more important to 
quickly find data items that are related lexigraphically. With 
enough work by a programmer, anv data structure will allow 
access to its data in whatever manner is desired; however 
every structure has certain patterns of access in which it excels. 
The Damocles' Sword that hangs over all embryonic programs 
is the fear that the need to manipulate data in non-optimal 
ways will crop up and results will be ugly and worse, slow. 

Choosing a data structure which performs poorly for 
the demands that are made upon it is to risk a program that 
runs too slowly to be useful. To avoid this result, one must 
either modify the algorithm or change the data structure. In 
most cases computer programming involves negotiating the 
incompatibilities between the most obvious algorithm and the 
most natural data structure. With this in mind, it is important 
to have a range of data storage methods available and to know 
their strengths and weaknesses. 

A hash table is a storage scheme which excels in quick 
deletions, insertions, and queries, and is a good match for 
programs that make heavy use of these functions. This article 
gives an overview of the concepts behind hashing, examines 
the situations were it performs well and those where it does 
not, and gives code for a standard library which will allow any 
user program to incorporate this data structure with just a few 
function calls. 

All Easy Example 

The choice of a data structure for a program is 
influenced primarilyby the nature of the data being stored and 
the way it will be accessed. Consider the following venerable 
computer science pedagogical problem: 

Write a program letters.c which determines the number of 
occurrences of each alphabetical letter in the input. 
Output should be a letter paired with the frequency of its 
presence in the input data. 



Of course one way to solve the problem is to have a 
lot of statements like if (input _ch == 'A') Num_A++;. Intu- 
itively, there must be variables which will keep track of the 
number of each letter observed so far, but to have 26 variables 
and 26 (/statements makes for an unnecessarily lengthy and 
cluttered program. 

One obvious optimization tactic is to use an array 
with 26 elements to hold the information about each letter — 
perhaps something like: 

struct letter_info 

char letter; 
short occurrences; 

struct letter_info table [2 6]; 

But which letter should go in tablelOj? Either we could 
put each letter in the order it first occurs in the input, or we 
could assign the tetters to the array indexes using the ordinary 
ordering: 'A' to 0, 'B' to 1 and so on. If we opt for the first 
method, then to update the information for a particular letter 
we would start at tableiOl and loop through all the elements 
until we got to one that is storing the letter we are interested 
in. This method is similar to the method with many //state- 
ments in that we rummage around to find the storage spot we 
need. The advantage is that now we need only one array and a 
short loop to accomplish the same thing. 

The idea of using the normal alphabetical ordering to 
position the letters in the array is more interesting still, (t 
almost seems redundant to store tablelO]. letter = 'A' because we 
know that the first letter will always be the first item. Even 
worse is the idea of looping through the array to find the 
information for 'D' when we know that it will be in the fourth 
slot. What we need is a way to turn this association into 
something that the compiler can understand. 

To do this, we use the fact that letters are given a 
numeric ordering in C by their ASCII codes. These codes aren't 
going to be in the same range as the array indexes, but by 
converting them, we can move freely between the idea of an 
alphabetical character and its position in the data structure. 
Figure 1 shows an implementation of letters.c that uses this 
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idea to reduce the whole program to a few lines. Notice that 
the program goes right to the array element it wants without 
searching to find it. 

Variation on an Easy Example 

A slight variation on letters just considered is the 
following problem: 

Write a program words.c which keeps track of how many 
timet individual words in the input file occur. The 
program should also keep a list of the pages in the file on 
which a word appears. 

The algorithm for this program is as simple as the one 
for fetters. Take the current word in the input file to see if it is 
already being stored. If it isn't, then tell the data structure to 
add it with occurrences = I. If it is already present, then just add 
one to the frequency count. The current page number is 
determined by the current line of the input file. 

For each word we will have to have a structure that 
keeps track of a number of things. We need a string to store the 
word itself. This field is known as the key field and is what the 
data structure will be organized by. The data structure will be 
geared to performing actions using the key field — find a record 
with a given key; insert a record with this key; delete a record 
with this key. Notice that we will never be doing something 
like looking for all the words that appear on page 48. The fact 
that we will be accessing data by only one key field will be 
important in choosing a data structure. 

Also we will need an integer to represent the number 
of times the word has occurred, and a list of integers that 
represents the pages that contain occurrences of the word. 
Some words might be in the file only once and so will have 
only one page in their list. Common words, however, probably 
appear on every page and consequently would have a long list. 
Because the number of pages will vary so widely, it makes 
sense to store the pages in a linked list so as to use only as 
much space as necessary. 

Likewise, because the number of items to be stored 
can't be determined until the program is actually run, it is 
necessary for the program's main data structure to be dynamic 
as well. A dynamic structure, such as a linked list, has its 
maximum number of elements limited only by the amount of 
memory available and can add new items while the program is 
executing. This contrasts with static structures such as arrays 
where the maximum storage space is fixed when the program 
is compiled. Notice that in lelters.c a fixed array size wasn't an 
obstacle because we had prior information about how many 
items would have to be stored. 

In most cases it is not possible to find items in a 
dynamic data structure by selection so a traversal system must 
be used. Selection is a method of data access where we 
compute the subscript of the array element we are interested in 
and hence are able to go directly to it. By contrast, in traversal 
the structure elements are considered one at a time until the 
appropriate item is found. In the final version of le tters.c , we 
were able to use selection to locate array elements. In order to 



determine if a given word is in the structure in a linked list that 
is ordered alphabetically, we follow a traversal procedure that 
searches from the beginning of the list until it finds the key (a 
hit) or a word that is lexigraphically greater, in which case it is 
known that the key word isn't present and the search can be 
aborted (a miss). 

Considering that almost all of the execution time of 
words.c will be the result of the time taken by operations on the 
program's main data structure, it is important to examine how 
a linked list will perform for an average query operation. 

For a given key word, it is possible that we might find 
it at the beginning of the list, we might have to search all the 
way to the end, or we might be able to stop the search some- 
where part way into the list. Over a large number of words, it 
can be expected, that we wilt be able to discontinue the query 
after checking half the list. So if we call the time taken to check 
a single record el, and let s be the length of the list (one record 
for every different word in the input file), then time taken by 
words to process a file with n many strings will be roughly n X 
(c] X s/2). Of course, as the program loops through the input, 
it will be expanding the list size s so this is only an approxima- 
tion; nevertheless, we can make some useful generalizations. If 
words were run on an on-line book that had a half-million 
words, 10% of which form the vocabulary for the book, then 
the program would perform something on the order of 12.5 
billion key checks; even assuming that ci is small this could 
take a long time to execute. Since we can't change n, obviously, 
to reduce the running time we need to reduce the time taken to 
query the data structure to as small a number as possible. 

Query time, then, is the principle concern in choosing 
a data structure to implement the algorithm for this program. 
In letters.c a method of interpreting the index of the array was 
used which allowed the data to be accessed with no searching 
at all. The length of time taken to access the appropriate record 
was basically the length necessary to convert the key into an 
array index; this characteristic is known as "constant time" as 
the queries always take some constant length of time regard- 
less of how much data is being stored. A constant time query 
data structure is important because no penalty is paid as the 
data size increases — in contrast to a linked list implementation 
of words discussed above, a hypothetical constant time version 
would need only half-a-million key comparisons. So if C2 is the 
time taken by a single constant time query, and if ci = c2, then 
this new program would be approximately 25,000 times faster. 
Apparently, a linked list would not be a good choice 
for the main data structure for words.c. Unfortunately, it is not 
obvious how to turn an array into a constant time query data 
structure which will fit this program. The first problem is how 
to turn a key word into an array index. The instance where the 
key is just a single letter is almost trivial; when the key is a 
string of characters things become more challenging. 

Secondly, assuming that we take the first 12 charac- 
ters of the key to be significant, there are over $52^2 possible 
keywords. Notice in letters.c there was a one-to-one correspon- 
dence between the number of permutations of the key and the 
size of the array. Now, however, it would clearly be absurd to 
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Figure One 

Listing ofletters.c 



/* letters. c */ 
# include <stdio.h> 
((include <ctype.h> 

char table [26] ; 
main ( ) 
{ 

int i, ch; 

while ( (ch = getchar(l) != EOF) 
if (isalpha(ch) ) 

table [toupper(ch) - 'A r ] += 1; 
for (i=0; i<26; i++) 

printf("%c: %hd\n'\ ('A' + 1), table [i] 
exit (0) ,- 
) 



allocate $5212 array elements, especially considering that our 
knowledge of the input data tells us that we will most likely 
need to store a few ten-thousand records. 

There is a theorem of combinatorics, known as the 
Pigeonhole Principle, which states that in trying to put u + 1 
object into n pigeonholes that some pigeonhole is going to get 
more than one object. Knowing that in dealing with a theoreti- 
cally huge data set of English words and the much smaller 
array size that can physically be allocated for data storage, it 
will be necessary to assign some of the possible key permuta- 
tions to a single array index; the second challenge is what to do 
when two such words actually occur in the input file. 

When we have methods for converting a string into a 
valid array index and for handling situations where more than 
one word key is assigned the same index, the resulting array is 
known as a hash table. Using this modified array, we will be 
able to insert, delete, and query items in constant time. It will 
turn out that some hash tables are also dynamic and hence a 
prefect fit as data structures. 
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Hashing Functions 

The term hash function is used to refer to 
both the function that converts a key into an integer 
and the function that converts that a key into a 
integer in the range of the array index. For the sake 
of clarity I will refer to the first function as g() and 
the second as h(). Obviously h(k) = g(k) % size where 
size is the number of indices for the array and % has 
its usual meaning as the modulus division operator 
in C. Of course the plan is to store the record with 
key k at tabklh(k)}. 

A hash function should satisfy the following 
criteria: 

• Should spread values over the full range. 

• Should be possible for short string to hash to 
large values. 



• Should be relatively quick to compute. 

• Should the preserve distinct nature of permutations 
alphabetical keys— "file" should hash to a different value 
than "life". 

• Shouldn't have a range with a disproportion of multiples 
of any number. 

• Shouldn't give alphabetically similar keys similar hash 
values.itemize 

Using the fact that characters are given a numeric 
value by their ASCII codes, we can essentially deal with a key 
string as a list of up to 12 numbers. The challenge is to turn this 
group of numbers into a single number in a way that meets the 
goals listed above. Notice that multiplying them together isn't 
a good idea as anagrams will get the same value, and it will 
not be possible to hash to a prime. The following is a modifica- 
tion of the method presented in Sincovec and Wiener's Data 
Structures Using Modula-2: 



Treating each letter as a 7-bit integer, break the 
key word up from the left into three clusters of 
four letters each (see figure 2). 

Shift all the bits in Cluster 2 to the left, 
one space. 

Shift all the bits in Cluster 3 to the left, 
two spaces. 

XOR clusters 1, 2 and 3 together. 
The result is g(k). 

ASCII is a seven-bit code which allows us to 
treat the letters as seven-bit integers without 
losing any information. Notice that the clusters are 
all less that 32 bits long and hence they fit into one 
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68000 series register. Because all the manipulations take place 
in CPU registers, the hash value can be computed quickly. 
Using this hashing function, 1 have found that in practice, 
regardless of the number of items stored, the average length of 
a non-empty list is about 1.5 for a table with 1-to-l ratio 
between its size and the number of elements in it. This constant 
time performance insures that queries will be quick. 

Collision Resolution 

To insert a record into the hash table, we determine 
the hash value of the record's key. If this array element already 
contains a record, the situation is known as a collision and the 
method of determining where to store the new record is 
known as the "collision resolution policy." Essentially there are 
two fundamental methods of proceeding— open addressing 
where the record is placed at some other index in the array, 
and separate chaining, the most generally useful scheme, 
where additional records are placed outside of the array. 

In separate chaining each array element represents a 
linked list of records which have the same hash values. Note, 
however, that these records don't have the same key. In 
performing a query on a given key, first the hash value is 
computed and then the linked list at that table index is 
searched in linear order until either a record with the desired 
key field is found or the end of the list is reached. If the end of 
the list is reached without finding a record with the sought key 
field, then it is known that record cannot be stored anywhere 
in the table. 

The dispersion of keys created by h(k) is critical to the 
performance of the hash data structure. The absolute worst 
case is if every key hashes to the same value — the access time 
will be similar to that of a linked list. Conversely, in the best 
case there is only one record stored at each index and so 
finding an element in the table will only take as long as it takes 
to compute h(k). If the hashing function gives an even distribu- 
tion, and given a table of size size containing s records, then we 
would expect each table slot to have size/s elements. So, given a 
judicious choice of the array size, access time will depend 
entirely on h(k), and consequently hashing will give the 
constant time queries that we desire. 

In an array, the entire data structure is stored in 
contiguous memory, which in effect means that the absolute 
memory location of any element can easily be determined by 
knowing the initial array location and the size of the objects 
stored (remember all elements are allocated the same amount 
of storage space). The memory location of element i is simply 
&table[0] + i X sizeof(table[Q]). The downside of this easy access 
is that the maximum size of the array must be specified at the 
time the program is compiled. As was seen above, while a hash 
table is never really full, it is advantageous to have the size of 
the table in a one-to-one ratio with the number of elements 
being stored. To help accomplish this, hashlib dynamically 
allocates the hash table using the callocO function rather than 
statically allocating it at compile time. And while it is still the 
case that the size of the table must be chosen before any items 
are stored in it, in practice it is often possible to determine 
during execution (perhaps through the use of a command line 
switch) the maximum number of elements to be stored. 



Obviously, the time taken by a query will depend 
upon the length of the linked list that is followed after comput- 
ing h(k) and hence the hash fable size will have an effect on 
performance. However, the numeric nature of the size will also 
have an effort on performance. Suppose that a certain table has 
an even number of entries, and suppose that g(k) produces all 
even values either because of a defect in the function or 
because the input data just happens coincidentally to be 
skewed with words that hash to even numbers. Then the 
values of h(k) will consequently be even and all the odd table 
indexes will never be used so the average length of a linked list 
will be doubled and therefore access time will be increased. In 
general if n is the size of a hash table which has prime factors 
ai,...,ak and if for some key k, g(k) has ai,...,aj among its prime 
factors, then h(k) will be a multiple of aj X ... X aj. So if there is a 
numeric artifact in the range of g(k), then h(k) will not distrib- 
ute all indexes equally and there will be a corresponding 
denigration in access time. In practice this means that prime 
tables sizes that are optimal. 

Standard Libraries 

Unfortunately the complexity of a program does not 
increase linearly in relation to the code size — rather it is the 
case that twice the code is likely to be an order of magnitude 
harder to understand. To combat this, a programmer must be 
rigorous in planning a project and in using proven methods to 
help control program complexity. The use of high-level 
languages, modular code, careful documentation, and stan- 
dard libraries and interfaces can be of great help in keeping 
complicated code understandable. 

Standard libraries offer a number of benefits to the 
programmer. They aid debugging by removing large sections 
of presumably proven code from cluttering the new, task- 
specific code. They also help by substituting a one-line, 
hopeful self-descriptive function call for an inline alternative; 
consequently, user functions are succinct and their purpose 
can be grasped mores easily. Furthermore, a standard library 
encourages the use of more sophisticated and efficient data 
structures by making their ease of use comparable with that of 
structures with built-in language support like arrays. This 
eliminates "quick and dirty" attempts to try out an algorithm 
which latter requires a rewrite for a different data storage 
method to make them practical. 

The hashlib Library 

Htishlib.c is an implementation of a hash table and the 
access functions associated with it that I have described in this 
article, It is an abstract version of a hash table in the since that 
it doesn't need to know about the kind of information the user 
is storing. So whether the routines are used with a program 
that stores payroll information or one that manipulates 
publishing data, the code in htishlib.c doesn't have to be altered. 
To accomplish this the library uses two header files and 
requires the user to provide three simple functions. 

The structure that the user program wants to organize 
in a hash table may be simple and consist of only a key field, or 
it might be very complex. However, for the purposes of 
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Imshlib.c, there are only a few things about the structure that 
are important. First there must be a way to refer to the struc- 
ture. The library expects the structure to be called by the 
typedef element. This definition is then put in a header file 
userdefs.h and is read at compile time. 

The library has no idea which field in an element the 
user has picked to be the key field and this is desirable because 
for some applications it might be employee _name and for others, 
BookTitlc — to hard code a name would be too restrictive. To 
allow kttShlib.c to access this field without having to know its 
name, the user writes a short function retkeyO which takes as 
input a pointer to an element and simply returns the value of 
whatever field the user has decided to organize the table by. 
Similarly, copying the contents of one element to another is 
done by another user-supplied function, copyelementO. Both of 
these functions can be placed in any source file as long as they 
are linked with the library code. 

Sometimes it is useful to have dynamic data structure, 
prehaps a linked list, perhaps a gadget, as part of an element. 
Of course, this structure must return its memory when the 
element is deleted. This is done by the function deleteelementO 
which the user writes and places in one of the source files. If an 
element contains no dynamic memory, then this function can 
simply be a stub. 

It has been my experience that it is extremely difficult 
to remember the correct interface required for a standard 
library function call (for instance, what is the order of argu- 
ments for qsortO), so I have tried to make the call format for the 
functions as simple as possible. To this end, I have eliminated 
the need for the user to keep track of a variable for the hash 
table by making it a global variable. Consequently, most of the 
calls involve only one variable and hence the danger of 
confusing call syntax is vastly reduced. On the downside, this 
prevents the use of more than one hash table in a program but 
this shouldn't present a difficulty for most applications. 

The following are the call syntax is for the hash table 
functions: 

short mnkehash(long) 

The input value is the size to make the newly created 
hash table. The return value is FALSE if memorv isn't avail- 
able. 

element* iiiserthashtelement*) 

The input value is a pointer to a element to copy into 
the table. If the new item is successfully inserted, a pointer to it 
is returned. In the event of an insertion failure, NULL is 
returned. 

element* findhash(clmrU) 

The input value is a the key string to check the hash 
table for. If a record with a matching key field is present, a 
pointer to it is returned. A NULL pointer signifies that the item 
is not in the table. 



short deletehnsh(chniil) 

The input value is the key string for a record to delete 
from the table. If the record isn't present, then FALSE is 
returned. It calls deieteelement(*element), which is defined in the 
user's program, to delete the dynamic memory, if any, that is 
associated with an element. 

element* dumplmsh(charU) 

This function is used to get sequential access to all the 
records in the table. The return value is a pointer to the record 
stored after the one with the key field that is passed to the 
function. An input value of NULL causes dumphashO to return 
a pointer to the first record and is used to start looping through 
the data. A return value of NULL means that all values in the 
table have been returned. 

void freehasli tablet) 

Because the memory for the hash table is dynamically 
allocated, it is necessary to use freeO to return it to the system 
when it is no longer needed. This function frees all the linked 
lists that are created when new items are inserted. 

To summarize the following need to be done by the 
user when accessing the library: 

1. Create the file "userdefs.h" contains the definition typedef 
element which is user data structure. 

2. Write a function copyelementQ which copies arg2 to argl, 
where the arguments are of type *element and place it in a 
source file. 

3. Write a function retkeyO which returns the key field 
associated with the argument *element and place it in a 

source file. 

4. Write a function deleteelementO which uses freed to deallocate 
any dynamic memory associated with an element and place 
it in a source file. Input is a pointer to an element. 

5. Include " hashdefs.h" and "userdefs.h" in all code files that 
access the hash library. 

6. In the main program call makehaslil) with an argument 
specifying how many records are expected. Before the 
program exits cal\ freehashtableO. 

7. Compile hashlib.C and the user program with long integers. 

8. Link the object files together. 

You might notice when examining liashlib.c that the 
function to compute the hash value of a key is split up into two 
macros. The use of a macro avoids the overhead of a function 
call and consequently runs about hi)",, faster. However, some 
compilers have a limit of 256 characters in macros, so I have 
split computelmshO up into two #defines to provide compatibil- 
ity with various compilers. 
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Draw Backs of Hashing 

The value of a data structure depends on how well it 
fulfills the demands made on it in a program. As we have seen 
a hash table is a method of data storage that has constant time 
queries, insertions and deletions. There are some actions which 
hash tables don't support well though. Because hashing does 
not preserve the lexigraphical ordering of the input keys, it is 
not possible to do wildcard searches and the useful relations 
that exist between contiguous elements in trees aren't there in 
the table. Hashing is not used to sort — its value is in programs 
with algorithms that make heavy use of queries on large data 
sets. 

There is also memory overhead associated with using 
a hash table. For every slot in the table there is a four-byte 
pointer to the next value. And for additional items in the list 
there are more pointers. The memory efficiency of the data 
structure depends on a good hashing function to disperse the 
keys and keep the collision lists short. 

Twists on Hashing 

There are collision resolution schemes quite different 
from the one described here where only slots in the original 
array are used to store elements. In some methods the new 
item is placed in the next available spot and there are others in 
which a second hashing function is used to pick another space. 
Using this kind collision scheme complicates finding and 
deleting items, but it can be useful in situations where it is 
desirable to avoid allocating memory dynamically. 

Another interesting use of hashing is as a space- 
saving compression scheme. The main idea here isn't to store 
items in the array by a numeric index, but rather to use the 
hash value as a shorthand for the actual key. To do this, we 
compute gSk), for a key k and then store it instead of the actual 
key. Because g(k) is a long integer which is only four bytes and 
k is a 12-byte string, there is an eight-byte savings for every 
key. Of course now it is impossible tell which key we are really 
-luring because we onlv have the hash value, bill for some 
applications this is acceptable. 

Algorithms and Data Structures 

Almost any data structure can be used with a given 
algorithm. Arrays, dynamic linked lists, AVL trees, heaps and 
hash tables all essentially do the same thing: store data and 
give it back again. However just like thumbtacks and staples 
they have certain jobs they do best. Picking the wrong tool, like 
a thumbtack to hold together a report or a hash table to sort a 
list of records, can have awkward if not painful results. There 
are many situations where a hash table will not be flexible 
enough to be of use — but in those instances where it is appro- 
priate, it is usually the best tool for the job. 



words.c 



I* words.c 

A program using hashlib.c to keep a count of the number of occurrences 
of words in a text file and the pages on which they occure. 



• include <st<3io.h> 
•include <ctype.h> 
Hnclude "userdefs.h" 
^include 'hasbdefs.h' 

idefine FALSE 
•define TRUE 1 

feel me PASELBCIH BO 
((define STRLEKJTH 19 

extern char* irallocll; 

char* reUe/tcataj 
element 'data; 

■: 

if (data == N 

return N 
else 

return. data->word; 



/* note that there is no need to copy page lists '/ 

■ pyeleraenttone, two) 
element *one, 'two; 



I 



(void) strcpylone->word, wo->word); 
one-xKcurrences = two->occurrences ; 
one->start_page_lis: - N 
one->end_pac;e_list = NOIL; 



) 



/* Used to free the linked list of page numbers that is part of an 
elarent. */ 
void deleteelenentldatal 
element 'data; 
| 
str.c: plist "cur, 'next; 

if ((data — HULL) II ( (cur = data->start_page_listl == NULL)) 
return,- 

for (next = cur->next ; r.ext != HULL; cur - next, next = next->next) 

free ((char *) cur); 
free ((char *) cur); 
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short copvwordfpos, one, two) 
char one[], two!]; 
short *pos; 
I 

short i; 

if (two[*posJ == -\0') 

return [FALSE) ; 
while (!isaipha(two[*posi)) 

if ltwo'+*(*posl] == '\0') 
return (FALSE); 
for (i -. 0; twofpos] !; '\0' IA isalpha(two[*pos] ) kf, i < STRLENGTH; 

('pos)-f-, :-•) 

one[ij - tolowerltwo[*posl); 
one[i] : '\0'j 
return (TRUE); 
1 

/* Adds a new page to the page list for the word stored in info. * 
void add_occurance(info, page) 
element 'info; 
short page; 
I 
struct plist *tatp; 

if Uinfo->endj)age_Ust != NULLI SS (info->end_page_iist->page ==page)l 
return; 

it ( (temp = struct plist*) rallce (sijeoflstruct plist)) ] =- NBLLI 
{ 

fprintflstderr, "Out of neroiy!\n*); 

exit (101; 
) 
tenp->next = NULL; 
tep->page = page; 

if (Lnfo->start_page_list -- 

info->start_page_list = tesp; 
else 

info->er.d_page_list->next = tenp; 

.■;_p=ge_::s: = tenp; 



void printpages [wordl 
element 'word; 



; 



struct plist 'our; 

for (cur = word->start_page_list; cur != NULL; cur = cur->next) 

printfl' Xni ", cur->page); 



: 



^ainiac, avl 
int ac; 
char *av[|; 
{ 

FILE 'textjile; 

char buffer[250], word[250J ; 

snort line, page, pos; 

element 'into, entry; 

long length; 



if (ac != 3) 
( 
fprintflstderr, 'USEAGE: 4s <text file> <length>\n\ avJO] 
exit (51; 



if (ltext_file = fopen(av[l), 'r"l) == KHi) 
( 
fpr:ntf(stderr, 'Could not open file *s.\n', av(l]); 
exit(5); 
1 
sscanf(av[2|, "%ld", (ilength); 

if ( ratehash((lor.gl length) == FALSEI 
( 
fprintflstderr, 'Could not irake hash table of size 41d.\n", length); 
exit 110); 
) 

/* Loop through all the input updating data information as 

necessary.-/ 
for(page=i, Iine=l; fgetslbuffer, 250, textjile]; line++) 
{ 

::' line == FAGELFJXTHj 



I 



line = 1; 

pagers; 
) 
for (pos = 0; copywordl&pos, word, buffer) ; 
( 

if I (info = findhash(word)) == FALSE) 



( 



entry. occurrences = 0; 

(void) strcpylentry.word, wordl; 

info = inserthashl&entryl; 
) 
(info->occurrence3) -= I; 
add_occurance(info, page); 



:• 



/* Display all the accnulated data. Notice the initial and t=rrr,ir.ation 

-= used with cupmhashll . */ 
for (info = dumphash(NULL) ; info != NULL; info = dutphash(info->word) ) 
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I 



print£l*$5 (thdl *, info->word, inf cooccurrences i 
printpages(info); 



fclose(text_iiiei; 
freehashtableO; 



HashLib.c 



iinclude <stdio.h> 
{include 'userdefs.h' 
tinclude 'hashdefs.h" 
Idefine FALSE 
sdefine TRUE 1 

/* KASKLIB.C 
Peter Dill 

KASKLIB.C is a collection of functions to define, create, and manipulate 
a generic hashtable. A hash table is an array whose indexes are related 
to the data stored there. This allows an element to be found in the time 
it takes to compute the index (called hashing) regardless of the number 
of items stored. This is contrast to a binary tree where the time to find 
an item can be loglbase 2ln or a linked list, n. 

Different keys can generate the same hashindex, so when a collision 
occures a linked list is made. So if the ratio of hashtable slots to 
items stored rises, preformance denegrates toward a linked list case. 

The memory for the hashtable here is calloc'ed so its size is determined 
by calling program. 

The hashtable is generic in the sence that the type of items it stores 
is determined by the definition of 'element' that the user provides in 
'userdefs.h*. The hashtable contains pointers to a structure called 
'packet' which contains an 'element' and a pointer to another 'packet'. 
This allows for a linked list. The definition of 'packet' is in 
"hashdefs.h'. 

For a program to interface with the functions four things are needed: 

1. external typedef needed for 'element' which is the type for the user 
data. Placed in 'userdefs.h" 

2. retkeyf] is an externally defined taction which returns the key field 
of an instance of '*elenent'. 

3 . copyelement [ ) copies arg2 to argl where the args are of type eleaent . 

4. deleteelesentO which takes a pointer to an element and deletes the 
dynamically allocated memory, if any, associated with it. 

These functions are placed in a file with the rest of the user code. 

Remember to connile and link with long integers. 



extern char* mallocd; 
extern char* callocO; 



long TahleSize; 
struct packet **ht; 



Sdefine coxpLtehashl(k,h)\ 
for |;(ktii] != '\0') && (ii < 41; iitt)\ 
(\ 
Cl «= 7;\ 

cl 1= k[ii];\ 
]\ 
for (;(k[ii| 1= '\0') IS (ii < 8); ii++l\ 
!\ 

c2 «= 7j\ 

c2 |= k[ii],-\ 



Idefine computehash2(k I h}\ 
for l;lk[ii] != '\0'l ik (ii < 121; ii++l\ 
(\ 
c3 «= 7;\ 
c3 1= k[ii];\ 
)\ 
c3 «= 2;\ 
c2 «= 1;\ 
h = (cl " c2 * c3l t Tables ize; 



void deletecham(lst) 
struct packet '1st; 
1 
struct packet *cur, *next; 

if ( (cur = 1st) == NULL) 

return; 
for (next = cur->next; next != NULL; cur = next, next • next->next) 
f 
deleteelement(&(cur->data) ) ; 
free (cur); 
1 
deleteelaient(i(cur->data) ) ; 
free (cur); 
) 

struct packet* makepacket (dt ) 
element 'dt; 
{ 
struct packet 'ptr; 

ptr = (struct packet*) malloc (Hong) sizeof (struct packet)); 
if (ptr ---- NULL) 
[ 
puts("\n could not allocate memory'l; 
return 'FALSE); 
1 
ptr->next = NULL; 
copyelementlMptr-xiata], dt); 
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/" input is the size for the new bash table. The return value is true :l 
the table was sucessfully made. It is desireabie to have the size 
equal to the maximum mraber of elements to he stored in the array. 

'/ 
■ makehashlsije) 

long size; 



long 



if I I (size »1] «ll == size) 

size -= 1; /* change to an odd */ 
TableSize = size; /* global, user wont have to keep passing the value*/ 
ht = (struct packet'*) calloclsize, sizecf (struct packet*) I; 
if [ht - NULL) 



I 



fprintf (stderr 

Dal .53izei 

return (FALSE); 



"\n Could not allocate memory for a %i table", 



| 

if |ht|3] !■ HDLLI 

for |i=0; i < TableSize; it+J 

ht[i) - 0; /* make sure the pointers are zeroed just in case */ 
return (M 



/' Input is a pointer to an element. If record with a same key as that of 
the input element is already in the table the item will not be added. 
Otherwise a new record is created with the sane field as those of the 
input and is added : the table a: the end :f a list. A pointer to this 
new record is returned. NULL indicates a failure. 

*/ 
element* inserthash(dt) 

/.-=7-.:.\ '::: 



0, c2 = 0, c3 = 0; 



register unsigned long cl 
register short i i = ; 
char 'key; 

unsigned long hashindex; 
struct packet *ptr, ":~; 



key=retkey(dt); 

corputehashl I key, hash index] ; 
cocputehash2 ikey, hashindex] ; 

for (tap = ht jhashindex] ; (tnp != NULL); tip = tmp->next] 
if (strcnplkey, retkeyl&ltrap-xiats 

return (BOLL); /* duplicate element */ 

ptr = cakepacketldt); 
if (ptr = NULL) 

ptr->next = ht [hashindex] ; 
ht [hashindex] = ptr; 
return Mptr->data)i 



/* Deletes the record with the key given by the input parameter. If 

no such record exists then FALSE is returned. 
V 
short deletehashlkey] 
char key!]; 
I 

register unsigned long cl = 0, c2 = 0, c3 = 0; 

register short ii=0j 

unsigned long hashindex; 

struct packet **ptr, "parent; 

ccaputehashl (key, hashindexl ; 
:: " :-:-;: ;ey - :..: 
if (ht [hashindex] =■ HOI " 

I ecurn FALSE) ; 
parent = ptr = &(ht[ hashindexl); 

while I Cptr != NULL] 44 (strcnplkey, retkey(i(i*ptr)-xlata))) !=0] ) 
( 
tirsz: : ptrj 
ptr = i((*ptr)->next); 
) 



if Cptr == NULL) 
returnlFALSE); 
if (parent == ptr) 
( 
ht [hashindex] = ht (hashindex] ->next; 
freeCptrl; 
) 



l*parent)->next = (*ptr|->next; 
free Cptr); 
•ptr = NULL; 



/* item sought is the at the head '/ 



) 

re: - :. "_': -. 



• 



I' Returns a pointer to the element that has the key given in the input 

parameter. If no such item is in the table, NULL is returned. 
*/ 
elenent* findhashlkey) 
char key[]; 
I 

register unsigned long cl = 0, c2 - 0, c3 = 0; 

register short ii=0; 

'unsigned long hashindex; 

struct packet *ptr; 

::■■: itehash (key,hashii I : 
canputehashi (key , hashindex ) ; 
if (ht [hashindex] == NULL) 

return (NULL); 
ptr = htlhashindex); 
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while ( (per \- NULLI tt (strcmplkey, retkey(i(ptr->data)l) != 0) ) 
{ 

ptr = ptr->next; 
) 
if Iptr == HILL) 

return (FALSE); 
return |&(ptr->data)); 



userdefs.h 



i 



/* used to get access to every item in the table sequentially. Returns 
a pointer to the element which follows in the table the record with 
the key given by the input parameter. To start pass the value NULL. 
A return value of BULL from the function indicates that all the input 
parameter was the key for the last item in the table or it wasn't 
present. 

V 
element "dusphashllastl 

char last[]; 

! 
register unsigned long cl = 3, c2 = 0, cl - 0; 
register short ii=Q; 
unsigned long loc, flag; 
struct packet *pos; 

if (last == NULL] 

loc = 0; 
else 
( 
coaputehashi (last, loc) ; 
ccaputehash2 (last, loc); 

for (flag = FALSE, pos = htllocl; pos != NULL; pes = pos->next] 
if istrcnplretkeylilpos-xJata]), last) == 0) 
1 
flag = TRUE; 
if (pos->next != NULL] 

return S(pos->next->data); 
) 
if (flag == FALSE) 

:■_•' -::. :."-"L; 
locw-; 
) 
for ( ;(ht[loc] == NULL) Uk (loc < TableSize); loc++) 

if (loc == TableSize) 

return (NULL); 
else 

return i(ht!loc]->data); 



/* called before Che user program exits to free all dynamic memory */ 
void freehashtable 1 1 
( 
long i; 

for(i=0) i<TableSize; i++| 
if (ht[i] != NULL) 

deletechain(ht[i]| ; 
free(ht); 



/* userdefs.h for words. cV 

struct plist 
[ 
short page; 

struct plist 'next; 
1; 

typedef struct 
I 
char word[20]; 

Bbort occurrences; 

struct plist *startj?age_list, *end_page_list; 



hashdefs.h 



/• hashdefs.h */ 



struct packet 



i 



struct packet 'next; 
element data; 



titdef _STTC_ 

extern void freehashtabled; 
extern short makehash ( long ) ; 
extern short deletebashlcharni; 
extern element* findhash(char[)); 
extern element* insertbashlelanenfi ; 
extern element* dumphash(char[]|; 

I* user supplied */ 
extern char* retkeyl element*); 
extern void copyelianent (element', element'); 
extern void deleteelementlelemsr;. ' i 

4else 

extern void freehashtable (); 

extern short makehash ( ) ; 

extern short deletehashd; 

extern eleiBent* findhashl); 

extent element* inserthashO; 

extern element" dumphashl); 

/* user supplied */ 
extern char* retkeyO; 
extern void copyelement ( ) ; 
extern void celeteelement () ; 
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Accessing the Math Co-Processor 
from BASIC 



R. P. Haviland 



FORWARD 

Amiga BASIC is a powerful version of the language, 
with hundreds of commands. It was well matched to the 
original Amiga 1000, making virtually all the Amiga features 
available to program control. 

Unfortunately, there is one area where the sponsors of 
the language version and the machine have not kept the 
language up to later model machine capability. This is the case 
for the expanded machines with the 68881 numerical co- 
processor installed, and for the accelerator boards of the same 
class. Amiga BASIC ignores the existence of the co-processor, 
so any performance gain is only the result of clock speed 
changes. This is in contrast to some of the Amiga Library 
routines which are provided, which check for the presence to 
the co-processor chip, and utilize it if present. 

Amiga BASIC does provide a way of using such a 
library, but the process is rather involved. The correct library 
must be opened, in this case the mathieeedoubbas. library or 
the mathieeedoubtrans. library. This requires the presence of a 
bmap file, unfortunately not provided for these libraries; it 
must be generated. 

The necessary functions are then made available with 
the DECLARE FUNCTIONid LIBRARY command. Thereafter, 
operation is straightforward, the defined function being used 
the same way as other BASIC functions. 

A method of avoiding these steps has been described. 
Essentially, a "WEDGE" is installed in BASIC, to intercept 
commands, examine these for new functions, and route them 
correctly. This technique was very common in the days of the 
Commodore C-64. It does have a drawback in that speed is 
reduced by the added steps of command examination. 
Unfortunately, the program to make this wedge has not been 
published by its originator. 

One way to avoid the roundabout steps is to program 
in machine language. Again unfortunately, the available public 
domain assemblers do not include the routines to assemble co- 
processor instructions. They are in several of the large "com- 
mercial duty" assemblers, but these can be expensive. Several 
of the C language compilers also allow use of the library 
functions. These techniques have been well covered in a series 
of Amazing Computing articles by Predmore, starting in issue 
V4.3 1989. 



In my case, I was not willing convert to C program- 
ming, or to completely rewrite a number of BASIC programs in 
regular use. In fact, I consider C to be a poor language for 
problem solving programs, because of the excessive detail 
required, detail which detracts from problem consideration. 
What I wanted was the ability to use the the math coprocessor 
within the structure and format of Amiga BASIC. 

THE CO-PROCESSOR from BASIC 

Amiga Basic does provide a tool to do this. This is the 
CALL command, which has three forms: 

CALL subroutine 



CALL library function 

CALL machine language routine 

With some maneuvering, either can be used to give access to 
the co-processor. However the machine language routine is 
faster, and about as easy to use as the others. 

The CALL routine does expect the target routine to be 
at a known address. While this is contrary to general Amiga 
programming rules, BASIC does provide a command, 
VARPTR(variablename) which can do the location operation. 
By far the easiest use is to set up an integer array whose values 
are the machine language code. The code must end with a 
return from subroutine code, RTS or &H4E75. 

Care must be taken with this, however. Amiga BASIC 
changes the location of arrays as new variables are encoun- 
tered. It is necessary to be absolutely certain that the V ARPTR 
command is not followed by a new variable. If this happens, 
an error in value can result, but more commonly there is a total 
crash, with a visit from the GURU. Check carefully before the 
program is run, or play safe, and place the proper VARPTR 
command just before the CALL. It is easier but more time 
consuming to reset all array pointers each time a CALL is 
made. 

The CALL does have a powerful feature. It can be 
written in the form: CALL routineaddress (lparamater, 
2parameter — ) where 1 parameter is the address of the first 
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parameter (a named variable), etc. These addresses are passed 
to the routine on the stack, which allows reading input values 
to the routine, and returning results. There is enormous 
flexibility here. 

THE CO-PROCESSOR 

Turning to the 68881 co-processor, it is designed for 
high accuracy floating point operation. Whereas normal or 
single precision floating point is 32 digits, and double precision 
is 64, the co-processor always uses 80 digits for internal 
operations. Paramater passing can be single or double preci- 
sion, with automatic conversion, and can also be a special form 
with 96 bits, 80 usable. Short 16 bit and long 32 bit integers can 
be used, as well as a special form for decimal digits. 

The co-processor has enormous capability. It includes: 

8 internal SO bit registers 

The arithmetic operations, +,-,.v,/ 

A table of constants 

A set of functions 

Register-register operations 

Register-memory operations 

Test and decide capability. 

These are implemented by adding a number of 
instructions to the normal ones of the 68000 family. All of these 
are of the hex form Fxxx, followed by one or more additional 
words. Because of the structure, these are usually called the F- 
instructions. 

USE OF RPN ARITHMETIC 

After several practice runs, it was decided that a 
reasonable compromise between speed and programming 
complexity could be had by structuring a set of co-processor 
accessing machine language routines to emulate a RPN 
scientific calculator. This is the type introduced by Hewlett- 
Packard just before computers started their popularity leap. 
This use has the advantage of previous acquaintance. It is 
familiar to most users of floating point arithmetic, and in any 
event is not difficult to learn. For the unintiate, in RPN the 
common process of addition is written as X Y +, rather than 
X+Y. This requires a stack to hold "pending operations", but 
eliminates the need for parenthesis. Internal computer arith- 
metic is often in RPN format, even though the programming 
uses the common form. 

In keeping with RPN usage, the first four of the 68881 
registers are used as a stack, designated as X,Y,Z,T. Since the 
registers are independent, FMOVE instructions are used as 
needed, with an extra register used for temporary storage. 
Operations are set to follow these rules: 



The input operation FSET copies the specified 
variable to the X register, the original value being lost; 

The FENTER operation copies X to Y, Y to Z and Z to T: the 

original value in T is lost; 

The FEX operation exchanges X and Y; 

The FUP operation copies X to Y, Y to Z, Z to T and T to X; 

The FDOWN operation copies T to Z, Z to Y, Y to X and X to T; 

The four arithmetic operations, FADD, FSUB, FMUL 
and FDIV combine X and Y appropriately, and place the result 
in X: Z is moved to Y and T is copied to Z: The original T 
remains: note that arithmetic operations in BASIC are un- 
changed; 

The constant operations read the selected constant 
into X: the original value is lost; 

The function operations replace the value in X by the 
selected function of X. An exception if FSINCOS, which places 
the cosine in X and the sine in Y: original values of both are 
lost; 

The output operation FGET copies X into the speci- 
fied variable, and nothing more. 

The selected constants were FPI, FZERO (used to 
clear X), and FBNL (or e, the base of natural logs). Other 
constants are available. 

The selected functions were: 



FSQ FSQR 

FASIN FATAN 

FCOSH FETOX 

FLOG10 FL0G2 

FCHS FSIN 



FABS FAC0S 

FATANH FCOS 

FET0XM1 FLOG10 

FL0GN FL0GNP1 

FSINH FTAN 



y.:-::\: 



FTENT0X FTCOTCK 



There is no provision for test and decision, or for such 
steps as divide-by-zero protection. These must be done in 
BASIC. 

Input and output is double precision floating point. If 
another format is needed, the conversion must be done by 
BASIC. 
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THE MACHINE LANGUAGE ROUTINES 

The machine language routines are held in arrays, one 
for each operation. These are named for the operation. Using 
FADD as the example, its array is first dimensioned, by DIM 
FADD%(8). The 9 array elements are then directly read into the 
array by a series of let statements. The address of FADD is set 
by FADD&=VARPTR(FADD%{0). As noted above, this step 
must be repeated to avoid crashes induced by BASIC moving 
arrays. 

For convenience, the ensemble of machine code is 
written as a block with BASIC labels in the 64000s. Similarly, 
the address assignments are a black at 65000. See listings 1 and 
2. 

The reason numeric labels are used is that the ON 
ERROR routine of BASIC will only tabulate errors by the 
nearest preceding label. The sparse label configuration so 
popular in "Structured Programming" may leave you search- 
ing through many lines of code for the error. The simple 
routines of listing 4 can be added to any program to simplify 
error finding. (If you are addicted to prettified code with block 
labels, indenting, etc, just add the line numbers. Once you 
debug and ensure the accuracy of 2000 or so lines of scientific 
code, you will appreciate the reason). 

If you wish, a set of instructions can be included in 
the program. Listing 4 is an example. 

It is worthwhile to spend a little time becoming 
familiar with RPN usage. Listing 5 is a core program for this. It 
first loads the value of PI in X then replaces it with the func- 
tional value of 2 to the PI power. The answer is copied to the 
variable A#. 

Use variations of the 500 block to exercise other 
operations. For example., insert 505 CALL FENTR&, and 515 
CALL FADD& to see the result of PI +2 to the PI power. In 
RPN notaion, this sequence is FPI, FENTER, FTWOTOX, 
FADD, FGET(A#). 

BENCHMARK TESTS 

The Savage benchmark is especially suited to a test of 
co-processor performance. Listing 6 shows a form of this in 
BASIC, to give a reference of performance without the co- 
processor. 

Listing 7 shows the same program in RPN form. Here, 
the unused elements of listings 1 and 2 have been deleted, to 
give as short a program as possible in this form. This step is 
not necessary, but saves program space and a little rim time, 

Finally, listing 8 shows an extension of program 7 to 
increase execution speed. Instead of calling separate machine 
language routines for each of the successive operations, they 
are combined into a single special routine, and given a special 
name. For example, the block from 410 to 480 in listing 7 is 
replace by the array SAVAGE%. The elements of this array are 
generated from the individual operations by deleting the RTS 
instruction &H4E75 from all but the very last operation. The 
resulting array has a dimension of 19. The advantage of this 
combination is that the computing overhead associated with 
switching between BASIC and assembly is greatly reduced. 



Running these last four listed programs will give a 
good picture of the improvement in accuracy and speed 
provided bv the co-processor. 

The following was found in a series of tests. All are 
for 10000 iterations, except the first, which is shown as 10 times 
the duration for 1000 iterations. The compiler used was AC- 
BASIC 

Amiga 500 

Listing 6, 434.8 seconds 

Listing 6, compiled, 30.5 seconds 

Amiga 1000 plus Sapphire co-processorfaccelerator 
Listing 6, 387.1 seconds 
Listing 7, 30.2 seconds 
Listing 8, 10.8 seconds 
Listing 6, compiled, 30.3 seconds 
Listing 7, compiled, 5.72 seconds 
Listing 8, compiled, 1.94 seconds 

Amiga 2500, includes co-processor 
Listing 6, 88.4 seconds 
Listing 7, 7,40 seconds 
Listing 6, compiled 57.3 seconds 
Listing 7, compiled, 1.68 seconds. 

For some reason, the 2500 showed the poorest 
accuracy in BASIC, the average error being 7D-5 per operation 
compiled and 2D-9 not compiled. For the 500 the correspond- 
ing values were 9D-9 and 2D-11. The enhanced 1000 gave zero 
error compiled (less than double precision resolution) and 2D- 
9 not compiled. With the co-processor in use, errors for all 
were 1.5D-14. 

The benefits of both the compiler and the co-processor 
are very evident And, of course, the benefits of the faster clock 
in the 2500 and the Sapphire board also shows. 

EXTENSIONS OF THE TECHNIQUE 

There are a number of possible extensions to this 
technique. One is to use the other three co-processor registers 
to hold temporary values. Another is to use either main or co- 
processor registers in index form to control loop execution. 
There are additional forms of many commands, for example, 
direct load and add. And the test provisions could be acti- 
vated, to eliminate the need for this in BASIC. 

In applying these techniques, remember the rule that 
20 percent of the code uses 80 percent of the time. Use the 
simplest form initially, then, if more speed is needed, use the 
form of listing 8 for the time consuming long loops. 

Time reductions of 10:1 are easily possible, and about 
100:1 can be reached by best use of capability, in summary, a 
co-processor plus a little effort can be very worthwhile. 
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LISTING ONE 



£3999 REM SOOTHE TO FILL RPH AMASS 

64000 :::■ ■■■: 

£4001 FSBni0)=aO2fiP:FSBI 

64010 ::: 

64011 FGm(01=UB26F:PGmil)=aj4:K :EGETtW=aHE75 

64020 rem am of data I o 

£4030 DIM FSimiol 

£4031 FBnsa(01=iHn00:fIHtR%Il)=sa3SO:FQm!l[2)=aiP200:Faniai 

64032 FFTOt(4l=4HF200:FETITRi(5).4HB0:FENTRM6l=^ 

E404G DIM FUPtllO) 

64041 FUP*(0]=tHF200:FU?4(!]=4HFBO:FtiFi(2)=4HF200;FUP*l3!=4l4980 

64042 FUP4l4]=4HF200:FOPS(5}=4H500:raFt|6)=SHF200:FUP'tt7!=4E80 

64043 FVJPl(a}=4HF200:FU?SI9)=«I':COO:FC?t(10)=4!i4E75 

64050 DIM FDOVMI101 

64051 FDOWM0]=iHF200:FDCWIS(I!=tH3B0;FD(*mi2b/ 

64052 FM*'4|4)=iHF200:FDCW«(5]=iKfl80:FE<Wni6l=iHF200:rK»n(7)=SM»O 

64053 FB»Itl9)=iHr200:FDCHit(9)=4KlD60:Fa»(»|!' 

M FBI* 161 

... ;FEfl 1 =HQ80:FEfl 3 i UK :FEM .,- 
64062 FHit(4)=tHF2M:FBa(51=aaC80:FB!»(S)=iH4E75 
64070 rh ' ■ mah:?l ; h::k; 

64080 DIM FADOtIB) 

64081 FADD% (0) =iHF230 : FADOI (11 =SJ»2 :FAEO% [21 ^lttF2£H)rFADQ% [ 3 ) =tH4O0 
640B2 PABD»|4)=SHF2'10:FADDl|51=tH880:FABBil6)=SHF200:FAIlM(7]=SHMO 
640B3 FADDI(8)=4H4E75 

64090 MM FSUBJI81 

64091 FElB»l0!=iHF230:FSUallll=4HA8:FaiB*(2!=itiF200:FSU8M3l=(.H400 

64092 F5UBll4hiHF2)0:FSUBSI5)=4HS80:F3JBtl6!=4HF200;FSUB5|7|54HM0 

64093 HSffl»(8)=lH4BJ5 

64100 DIM FXULM8I 

64101 M&«(t))=SBF!30:FM)«(l|=iBM:Fa3M(2)=aira0C);IlOUl3)=iE400 

..-?230:FMUL*l5)=SH880:F«ULil6) I SHF200:F»jL"' : ; : 

64103 FKUUI6)=4ri4E75 

64110 DIM FDMIBI 

64111 FDIVMO)=SflF200:FDIViU)=4KAO:FDTV![2)=lHr200;FDIVM3l=4H400 

64112 FDIVt(4|=iHF230:F3I'^(5|=tHBaO:EDIV«(6)=tHF200:FD: , ;> -■■>:. 

64113 FDIVi(8)=4H4S75 

64119 REM END OF ARITHMETIC OPERATIONS 

64120 DI" 

64121 FP:»|0|-: :FMU2>=*H4E75 

64130 DIM I 

64131 FHltl|0]=tHF2(»:FB»Dt 1 =SH5C . . 
64140 DIKFZEKMI2) 

?;:■;: F7EBO* ioi =iHF2ao : jlz?::* . =;h:ccf:fzssom:>' . 

64150 DIM FOJEt(2) 

64151 FONE%(0l=4HF200:FONESII|*£H5C32:FONEt[2]=4H4575 

64159 REM END OF CCHSTAHTS, START RUCTIONS 

64160 DM FSQS12) 

64161 FSQ*(0)=&HF200:FSQill)=4E23:FSQ![2)=4K4E75 

64170 DIM FEQS»(2) 

64171 FSQR»l0)=iHn00:FSORSIl)=SM4:FSORiC 
64180 DIM FABSK21 

. =4K!8:FA3SS!: 

64190 DIM FACOSH2I 

64191 FfJLX!SS(0)=lHF200:FACOS*(Ll=iHiC:FACOS4(2)=lH4E75 

64200 DIM FASIK4I2) 

64201 FASItmO)=SHF200:?ASINt(i>=iKC:FASINK , I 
64210 DIM PATAU* 121 

6421! FATANt(0)=iKF200:FATANKll=4HA:FATAK*l2)=iH4E75 

64220 DIM FATASHK2I 

64221 FATAKB 10) =&BF200: FATANHS ( 1 ] =4HD iFATANK! 1 2 1 =SH4E?5 
64230 DIM FC0SII2! 



64231 FCQ5*[Q)=Sffi200:FCOS4! =SH!D;FCQStl21 i 
64240 DIM FCOSH4I2) 

=SHF200;FOOSH I = hL?:FCOSH%(2l=-. 
64250 DIM FETOXM2) 

SlOiPBKKiai-UM 
." FEKHKHI2I 
64261 FlHO^»IOI=4jiF200:FETQ5WAi:i=4K£:FETO»!ltl.' 
64270 DIM FL0G10t(2) 
6427! FUIcaOtt0)«HtraOT:Fl«31O*lll=M15:FI/)SlO»(2]=tlMS75 

64280 DIK FUK2K2I 

64281 FLOG2i(0|=tHF200:rjB2l(l]=S816:FlOC2»(2)=4H4E75 
64290 DIM FLOGN*(2) 

6429! FWGS«(0)=SKF200:FlOOa(l)=&Hl4:FLOGHtl2)=iME75 
64300 DIM flog:f1*{2) 

- ::i:FL0GNFlt(II=SH6:FL03ff»: - 
643:0 DIM FCE=i'2] 

:■ CRSt 1 1 =4KF200 -.FCHSt 1 1 1 =4fllA:FCHSi 12] .4H4E75 
KFS33 - 
6432: ;:::. . -_.;...: :.-. 
64330 na Fsracoa 

=5BK :::?;:::::=! : =SH31:FSDCOSI - MSI'. 

64340 dih psmmai 

64341 FSIlffl»(0t=4HF200:FSINHt(lUiH2:FSItiH»l2)=4H4E75 

64350 DIH FTA1HI2I 

64351 FTANt(0|=£HF200:FTAKIU)=4HF:FTA]l«i2l=4H4E75 

64360 DIM FTAHHt(2) 

64361 PTANHI [0) =SHF200;FTASHt 1 11 x4R9:FTA!IH* (2 1 =4K4E75 
64370 DIM FTE,TOX4(2l 

';:a«i0!=iff200:Fi27To:a(!i=4H;2:FTEirroxi(2):iS4r7; 

64380 DIM F7t*M\ 

64381 PMOTOM . -..::. .::T/OIOKI(II=iHlI:F™OK):tl2|=4H4E75 

■.;, .:...: 



LISTING TWO 



64999 REM ROUTINE TO SET ADDSESSSS OF RPH ARRAYS 

65000 FSETS=VAF.PTR(FSET*tO)l 
65010 FGET4=VARPTRIFGET%(0)> 
65020 REH END OF DATA I/O 
65030 FBI PHH!»«»] 

. Jrtioii 

65050 FDCM14.\W.PTRIFDOW»(0)> 

55060 fe»=v&w>tf PEtHOI) 

65070 REM END CF iTAC-: XAiriFLLATT::; 
65080 FADM=VARPTR(FAH 

65090 FSU3i=VAKFT?.<FSU3l(0>) 
65100 FMUl4=\'ARPTF.IFKJL»((]I) 
65110 FD!V4=VARPTP.(PDIViiO)) 

65119 REM END OF ARITHMETIC OPERATIONS 

65120 FPIfcVAR?7R[Fm(0)l 
65130 FBNL4=VARPTR[FHiLt[0)) 
65140 F2E=Oi=VAF.?TR(FZEF.OM0) I 
65150 FONK=VARPTR[FONEtl0ll 
65159 REM BE : - 

=VARPB FSQI : 
f - SAHJT8|FS0S*(0)] 

65180 FJ SBS*(0(| 

65190 FACOS4=VAF.PTR (FACOS4 1 01 1 
65200 FASINt=VARPTR(FASlKMO!l 
65210 FATASi=VAEPTRIFATANilO)l 
65220 FATAHHfcYARPTSfFATAJHttGI I 
65230 FCOS4=WROTtFCOSi|(l] 1 
65240 FC0SH4=VAP.PTRIFCOSHI(0ll 
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55250 FETOXS =VARFTK ! FEIOX% I Q ! 1 
55260 FETOXMIt=VMtprK(FETOXMll(0lt 
55270 FLOG:04=WJ.PI?.(?LOG1K(OI! 
55280 FLOG24=VSBPIH(FKB2%(0l| 
55290 FLOGK4«VMm(FL0Q«(0l) 
55300 FLOQ.'FUA'.WfTHiryCIGKPlllOII 
55310 PCHSMfflRJP3H(PCHSttO|] 
55320 fsiis=varptr(fs:: ■ 

55330 FSIHMSiiVARPTHIFSDOBHO!) 
55340 FEIM!i=VASPrBIFSDWSI0!l 
55350 FTANS=VARPTR(FTAN*(0)] 

WPIR(nSB«t(!l|] 
65370 FTENTOXS=VARm(FTEJfTOXt(0)) 
553B0 FTWraXt^VARPTRlFTiiOlOXilO)) 

653 sc return 



420 

500 CALL FPI5 
510 CALL F7XR0Y.L 
520 CALL FGETilAPTRM 
530 CALL FEW 
■ ; :-:: ■;: : -i:y. 

600 PRINT Al 

610 PRINT B# 

700 REM ADD ROUTINES OF LISTING] AH I 

710 REM (64000 AND 65000 SEHIESI 

720 REM THESE .WE HEEDED TO COMPLETE THE PROGRAM 

730 RBI MODIFY THE 500 BLOCK OF CALLS FOR OTHER OPERATION TYPES 



'expect errors or crashes if not properly used 
'example of setting a constajr 
'example of an operation 
'example of i/o 
■example of stack kanipouticb 

'check. results 

,isti:b2 here 



LISTING SIX 



LISTING THREE 



: REM ERROR SERVER ROUTINES 

3 ON ERROR GOTO 60000 

50000 PRINT "ERROR *;ERR;* AT LINE ";ERL 

60100 REM EXAMPLE OF DIVIDE BY ZERO ROUTINE 

60110 IF ERL^X THEN VARIABLE=VARIABLE»1E-09:RESUME 

60200 REM EXAMPLE OF A FILE NOT FOUND ROUTINE 

60210 IF ERL=Y THEN PRINT 'FILE MOT FOUHD-REENTER FILEPATH, HAKE'; PESUffi Z 

60300 REM EXAMPLE OF A RETURN TO MENU 

60310 IF ERLrF THES INPUT 'PRESS RETURN TO RBCOVEB FROM ERROR\T$:EESUHE Q 

60400 REM EXAMPLE OF CLOSEODT 

60410 PRINT "ERROR RECOVERY NOT POSSIBLE' :STOP 



LISTING FOUR 



63000 'USING THE RPN CALCULATOR FROM BASIC 

63010 'WRITE THE EQUATIONS IN RPN FORM; CHECK THAT THEY CAN BE SOLVED 

63020 'WITH A 4 REGISTER STACK. USE INTERMEDIATE VARIABLES IF NECESSARY. 

63030 'SELECT THE VARIABLE NAMES, APPENDING A I FOR DOUBLE PRECISION. 

63040 'TRANSLATE THE RPN EQUATIONS TO COMPUTER FORM. IT IS USUALLY EASIER 

S3050 'TO PLACE EACH OPERATION CALL ON A SEPARATE LINE. 

S3060 'ADD THE 64000 AND 65000 ROUTINES AND THE NECESSARY G0SU3 COMMANDS. 

S3O70 'WATCH THAT ROUTINE ADDRESSES ARE OTKECTED AFTER VARIABLES ARE 

63080 'INTRODUCED. AN INITIAL VARTABLEI.O CAN SIMPLIFY WORK. 

:■-: ::;: ~z ~.:-i:-x> :::::- .; :■:■: .:. ;l: :- .:,.. ;; . 

63100 'WHEN RUNNING CORRECTLY, EVALUATE BENEFIT .? .C-ITLNG SPECIAL ROUTINES 
63110 'TO ELIMINATE MOVEMENT 3ETEEN BASIC AND RPN. THIS SAVES THE, 
63120 'ESPECIALLY WITHIN LOOPS. 

201 3= GENEROUS WITH BACK-OP CO:- . ' 7f TO HAKE A MISTAKE 

63210 'WHICH WILL INDUCE A CRASH. AVOIDING THESE IS EASIER WITH PRACTICE. 



LISTING FIVE 



• : -:'~::s fo= ?;:: vse OP GS381 1 

20 REM 6B881 CALCULATIONS M EXTENDED 80 BIT 

■'■-■; ! ALWAYS DOUBLE PRECISION FLOATING POINT 
40 REM RFN STACK FOLLOWS RPN I,Y,Z,» BULBS 



IDC AM 

200 GOSUB 64000 
210 GOSUB 65000 
300 APm=VARFTRIA#! 
310 BFRTS=VARPTR(B*> 
400 GOSUB 65000 



in 



■NECESSARY 7C SET .'AF.IAELE 

'FILLS ARRAYS WITH ML ROUTINES 
'SETS ADDRESSES OF ML ROUTINES 
'EACH VARIABLE NEEDS A POINTER 
■-.;-: V.ARIA3LEE \~ '_. 
' CORRECTS ADDRESSES IN NON-COMPILED BASIC 
'SINCE ARRAYS ARE MOVED AS VARIABLES ARE CREATED 



10 rem basic savage benchmark 

100 input 'ester number or loops' ;lco?l 

110 s:aat=t:kee 

! M=H 

210 FOR K*=l TO LOOP* 

220 At=TAS(ATNIEXP(LOG[SQR(A*-2|ll)Kl 

230 NEXT Ni 

300 TBtMIHER 

310 PRINT 'RUN DURATION. MEND-START; 'SECONDS 

320 PRIST 'ERROR=*;Ae/(LCOPitl|-I 

400 INPUT 'PRESS RETURN TO END'iTS 

4! i r~ 

500 REM NOTE EFFECT OF USING AI'.M IN LINE 220 



LISTING SEVEN 



: -■:• REVERSE POLISH SAVAGE E2GHASK BSJSS 68881 3L1 i FROM BASI 

100 Al=0 'SET VARIABLES, NOT REQUIRED IF SECOND CALL 65000 IS CORSSCT! 

110 Ni=0 

120 LOQPM 

130 STARTS 

140 APTRirVABPTSIAfl 

200 GOSUB 64010 'FILL ARRAYS 'WITH ML 

210 GOSUB 65010 'SET RPN POIHTHiS 

220 INPUT 'ENTER NUMBER OF LCOPS'.-LOOPI 

230 GOSIB 65010 

300 STAST=TIMEF. 

310 call F;:;t5 till state :~.~. ::rss 

320 CALL FENTEA 
330 CALL FENTRi 
340 CALL FENTRi 
410 FOR N»=l TO LOOPJ 
420 CALL FSQ4 
430 CALL FSQRA 
440 CALL FLOC-lti 
450 CALL FTENTOXt 
460 CALL FATAN4 
470 CALL FTANi 
490 CALL FADDi 

-• ::et-:t ::■ 

503 CALL FGETi APTRii 

600 TENCfcTIHER 

610 PRINT "RUN DURATIONS rTEND-START; 'SECONDS 

620 PRINT 'ERROP.=';A*/(LOOPStl]-l 

700 INPUT 'PRESS RETURN TO END'.TS 

1000 STOP 

HOW DIM FGET*:4) 

64011 FGET4l0]=SH226F:FGETI(l|iiH4:FGETil2)=iHF211;FGETS|3}=iH7400:FGETtl4]=tH4E75 
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; ddi rannnei 

64031 .-^JT3»(DI=tHF200:FB7KtU)=SH9JO:FSJTMI2)=iKF200:F2.TR's(3l=a5M 

64032 F2JTatHI=iKr200:FQrn»(5l=B!Bii:rEllTR»(6)=U(4E75 
64030 DIH FADD%(8) 

64081 F«MI0|.MF2OT:FMffl%lll=tHU:F»DM(2l=Uff21ll):FAl»»l3l=«B00 

64082 FADM (4 ] =iKF20Q:FADD% I S) =!,HB80:FACD% ( G I =6HF10D :FADD% C3 ) =AHD00 

64083 FADD»(!]=iH4E75 
DIKFOKB(21 

5415 - •:£i[0)=Sffi20O:FtHn(l)=UI5C32:FaiE*(2]=Ui4E75 
64160 DIH FSQ112) 

54161 FSQil0^5HF200:FSQ»(l)=4H23:FSO«(2)=&H4E75 
64170 DIH FSCRt(2> 
11 . FSgBl(0)=aS200:FS0RI(l)=aa.'FSQRI(2)iSHW5 

64210 DIH FSTM%i2) 

64211 FAT«ntO)=HiF21)0:FAIMB|l)=SHA:FAraS*(2l=iK4E75 

64270 DIK FLOG10K2) 

64271 FliOG10»IO)=SHF200:FLOG10tlll=4H15:i r IOG10t(2) I iH4E75 

64350 DIM FTAN4(2) 

64351 FIMJt(0)=SHF200:FT«flll)=(SF:FTA»lt(2|-aME75 

64370 DIX FTENKKi(2t 

64371 £Tcm)Xi{0)=»HF200:-7aiT0X»(l)=tK12:rTH?IOXt(2l=iH4E:75 
64400 RETURN 

- 5 S '. ■: FGEK=V»RPTB ( FGEIt 1 1 1 

65030 FFjnrti=\ttiiPTft(FFjfrsKOii 

650B0 FMIfcVARPWFADDllOI 1 
65150 FONES=VARPTH<FC«Et(0ll 
65160 FSC4=VAR?TR[FSQ%(0ll 
65170 FSQ«4=VAR?TR<FSC;Rtl0ll 
65210 FATANUVARPTRlFATANtlOl) 
65270 FLOG10i=VARFTR(FLOG!OilOn 

OHtO)l 
65370 FTEHraX^VMFTSiPTEKTCMIO)) 
65390 RETURN 




Do you want to 

write a specific article 

for 

ACs TECH? 



(7\ Call the Editor at 
^ (508)678-4200. 
He will be glad to 
hear from you! 



LISTING EIGHT 



10 REM REVERSE POLISH SAVAGE BE"Ky.-.= :' "SV.K : 

20 rem aid cs savage fc~::; entirely ::: as- 

.:: AM 'SET VARIABLES 

no ns=o 

: :■ : : : v . = 

130 STASH) 

140 APTKi=VARPTRiA*) 

200 GOSBB 63000 'FILL ARRAYS WITH ML 

210 GOSH 65000 'SET SHI FQWTEHS 

220 INPUT "BITS'. KLXBEB OF LOO?S-;LOOPS 

230 GOSDB 65000 'INSURANCE RESET 

300 START=TIHffi 

310 CALL POKES 'FILL STACK '.:::- '.- 

::: ".:: :. -l 

330 CALL FENTRi 

340 CALL FENTRi 

400 FOR Ni=l TO LOOK 

410 CALL FSAVS(APISi) 

420 NET N6 

500 CALL FGEWAH851 

600 TEKB-THH 

tic frh;. ■ ■■■::■. :■-■-. tend- start,- -seconds 

620 PRINT -ERSOR=-;A«/|LOOPS»1)-1 

700 INPUT 'PRESS RETURN TO ENDMS 

1000 STOP 

63000 'SAVAGE IN A3SEH3L: 

63010 DIM FSAVSU9) 



61 CALLS FRCH BASIC 



63020 
63040 
63050 
6306C 
63070 
63D80 
64090 
64091 
63100 
64010 
64011 

-;::: 

64031 
64032 
i«5( 
64151 

■;- 

65000 
65010 
S5030 

65150 



FSSVt [0] =£HF2CiO ; FSAVI [ i I =4H23 
FSAVI 12 ! =SHF200 : FSAVI [3 1 =W4 
FSAVI (4 1 =SHF200 : FSAVI 1 5 1 =SH15 
FSAVI [61 =5HF200 :FSAVl [7 ) =SH32 
FSAVI 1 81 =SHF20O : FSAVI {91 =IHA 
FSAVI 1 101 =1HF200 : FSAVI 1 11 1 =SHF 



'■ : : 

•ROOT 
'LOG10 
•■-.">. 
'SJMI 

'TAN 
FSAVI(0]=mOO:FSAVIU!=£IM:FSAV«(2)*iHF200:FSAV»(3|riH400 'ADD 

■.. j:FSAV*l5|TiH88O:FSAVi(6)=iHF200:?SAVl(7)=iHD00 
FSAV*|12!= 
DIH FGST4|4) 

FGm(0!=a226F:ram[l!^iH4:FGEn(2)=HF21I::GETS(3)=SH7400:FGETi(4)=SH4E75 
DK FENTRII6) 

FBim(l0]=tKF20O:FENTR4lll=SH980rFS(rrRil2)=iHF200:Fam(tl3)^H500 
FE»TRKil=MIF2[H):FEimi|5l=5HB0:FBJIRS|6) = i!: 

DM fonej::' 

FONEll0)^iHF200:FONE%(l]-SK5C32:FOHESI2)=ii-4E75 

mam 

F»Vi=VASJTRlFSAV)(0)) 

"-^YARrTRIFGETIIO)) 
FE»TRS=VARPTR IFEHTRt [ 0) ! 
FOtiE4=VARFTR(FONE*(0)) 
RETOBM 
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• These Amazing Dealers also carry AC's TECH, the #7 disk-based, all-tecbnicat publication for Amiga users. 

Amazing Computing is also available in most B. Dalton Booksellers, B. Dalton Software Stores. 
Crown Books. Software Etc., and selected WaldenBooks Stores and Walden's Software Store locations. 



AC TECH^MIGA Reader Service Card 
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Street 

City 

Country 



Suite 



ZIP 



At your opton. please provide trtj tolrowma data: 
1. Waf O 3. Mamed 

2. Ferrate O 4. 5inofemever marked 

D £ Separa'ed.w>dawcc 
Wha! is your age'' 

6. Undei IB O 9 35-(9 

7 10-24 O10. 50-64 

8. 25-34 OM 65 or over 

When cl me loiewinc- do you now own? 

(please cnecX an that apply! 

Ol2 A.Tirf;a3DQ0 Oi5 Amiga 10M 

013. Am«ga2SQ0 016. Amiga 5 DO 

014. Amiga 2000 01 7- do not own an Amuga 
Where do you use your Amgalsj. and aboul how many 
hours per v#©flk do you use an Amiga ill each location 7 
019. A! home 



G Wnal tanguag* do you most oiicn program in 1 ' 



a. 



019 h-T-L ,-M--m 

(ryptiot Ui&nt&i . 
02 j Al work 

llypeoi business . 
021 - A| school 

lappJiCalrans _ 



. nours per week 
. hours per week 



. hours per week 



TOTAL hours per week 

E Please indcale the primary and secondary applications 
lor wh«h you use youi AmjQai{s): 

22. Primary 

23 Secondary . 

F Please indcaiatne level aiwnicn you now consider 
fOurseJ io oe programming the Amiga: 
02J Eejjnnei 026- Advanced 

025. intermediate 027. Do not program 



How much money are you Lines* To spina on all 
Amga product purchases ina year 7 
[ail pcrsorvil and business education lor which you 
have lsna.i decision, combined) 
023. Lass Ihan5250 034 52G01-550PO 
OSS. J5OO1-57500 

036 S7501-S1DQOO 

037 Owff i -510000 



□33 S251-S500 
03V KOl-SlOOO 

032. 51M1-51S60 

033. S1501-S25O0 



How aid you cctairi this issue c-1 AG's TECH'' 

038. Preordered thus issue pnor lo its publication 

039. Ordered Irvs issue aHer seeing <1 elsewhere 
04u_ Ordered a charier suhscrplion. 

041:. Purchased h ai my Amiga dealer. 

How mar*y gran not including youisen have read 1 
win read thus ssue ol AC'S TECH 7, 



0-12. . 



_ oilers, m ado-iron to myself 



AC'S TECH Volume 1.3 

Valid until 10/15/91 

See page 65 lor reference numbers 



Overall, how would you rale this issue nl AC'S TECH 
in the areas indicated? 

Edtonatcanten j: L^lL 

043. Excellent 047. Excellent 

044. Good 04fl. Good 

045. Far Q49. f= air 
046 Poor OSO. Poor 

Do you raouiariy read or subsenbe to Amazing Computing? 

G51 I am a subscriber |p AC 

052 l read, but do not suSrscripe lo AC 

053. Do noi icaScf subscnoeto AC 

Have you ever purchased a copy Ol AC & Guide'' 

05J. Yes 055 No _._ 
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AC TECHMMIGA Reader Service Card 



Name 

Street 

City 

Country . 




State _ 



ZIP 



Ai your opiion. ptease provida ine lolLowtng oata: ( 

1- Male 3. Married 

2. Female O 4 Sing'^emever married 

O S- SeparHJedrWidowed ' 
What is your age? 

6. Under IB Q 9 35-*9 

7. 16-24 OIO 50-64 

8. 25-34 011 6& or over 

Which ol ihe following: do you now own."* 

iolease check a:t trial apply) 

012. Amiga3000 015. Amiga 1000 

013 Amiga 2500 Olfi Amiga 503 

014. AiTtga 2000 1 7 do noi own an Am>ga ' 

Where do you use your ARiiga[sj. and about now many 

hours pei weeK co you use an Amiga a: each locaiion 7 



. hours per week 
. hours per week 



. nours per week 



hours per week 



016. At home 
019 1 Home oltce 

(type 01 busjness 

O20 AI work 

(lype ot txismess 

021. Al school 

(aoplcjiions _; 

TOTAL: houis per week 

Please indcale Ina primary and seairidary appiCalcrs 
lor wtu^h you use vouf Amiga(S): 

22 Primary 

23 Secondary „ 

Please indicate the level ai which you now consider 
yourself to be ptOgrammm.i3 ina Amiga: 

024. Beginner 02G Advanced 

025. Iniermed'aie 02? Donoi program 



Wnai lanouafje do you most otien program in? 

2'i 

how much money are you bkeh- 10 spend pn aa 

Arnga prodUCl purchases l'tii$ yto&i^ 

\ki\ personal and tusiness/educalion lor which you 

have tanai decison. combined] 

023 Less than $250 034 !250l-i5ftCQ 

035. S50O1-S7500 

036. 57501-51 0000 
037 r>e-r *10W0 



03&. I251-JS0Q 
031. S50 1-11000 

032 5100l-$t500 

033 S1501-S2500 



How did y&u ob:ain this ssue 01 AGs TECH? 
036. Preordered this issue pnor 10 -is publcanon 
033- Ordered n:s issue alter seeing il elsewhere 
043 Ordered a cnaner subscripion. 
041. Purchased Hal my Amga dealer. 

How many others noi including yourssrl have read 1 
wlII read Ifvs issue of AGs TECH 1 ' 



_ ethers, m addrlion to myself 



AC'S TECH Volume 1.3 

Valid until 10/15/91 

See page 65 for reference numbers 



Ol2. _ 

Overall, how would you rale irns issue 01 AC'S TECH 

m tne areas macated? 

BaaMjapaMt: mk 

043 ExceBeni 047. Eiceiient 

044. Good 045 Good 

045. Fair 049. Fair 

046. Poor 050 Poor 

Do you regular*/ read or subscribe lo Amazing Compuimg? 

05! I am a suDscntier to AC 

052 I read but do not subscnpc to AC 

053. Do not read or subscribe io AC 

Ha»>e you ovnr purchased a copy of AC'S Guide? 

054. Yes 055. Wo _-_ 
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SAVE! SAVE! SAVE! 

If AC's TECH is just what you've 
been looking for in an Amiga 
publication, don't just sit there - 

SUBSCRIBE! 

Also consider two more great 
reasons to be a subscriber -AC 
and AC'S GUIDE! Just fill out, clip 
and mail this card along with your 
payment to pick up on the 

SAVINGS! 



r 



YES! The Amazing AC publications give me 3 GREAT reasons to save! 
Please begin the subscription(s) indicated below immediately! 

Name 



Address . 
Cily 



Slate 



ZIP 



ji ■ Iff} 



Charge my □ Visa □ MC it_ 



Expiration Date . 



.Signature . 



VISA. 



Please circle to Indicate this is a New Subscription or a Renewal 



1 year o! AC's TECH 


4 big Issues of AC's TECH! 
Untiled Time Charter Offer! 


US$39.95 1 1 

Canada/Mexico $43.95 □ 
Foreign Surface $47.95 □ 


1 year of AC 


12 big issues of Amazing Computing! 
Save over 49% off the cover price! 


US $24.00 □ 

Canada/Mexico $34.00 □ 
Foreign Surface $44.00 □ 


1-year SuperSub 


AC + AC'S GUIDE - 14 issues total! 
Save more than $31 off the cover prices! 


US $36.00 □ 
Canada/Mexico $54.00 □ 
Foreign Surface $64.00 □ 


2 years of AC 


24 big issues! Save over 59%! US only. 


US$38.00 l_J 


2-year SuperSub 


28 big Issues! Save more than S75! US oniy. 


US $59.00 l_J 



Check or money order payments must be In US funds drawn on a US bank; subject to applicable sales tax. 



Please return to: 



AC TECHJ&miga 

P.i.M. Publications, Inc. 

P.O. Box 869 

Fall River, MA 02722-0869 



Please place this order form in an envelope 
with your check or money order. 



n 



A 



XmazinsAMiGA 

A. COMPUTING C7Jr 

AC TECH Amiga AC" GUDE/amiga 




Name_ 



Address . 



■^^^^^^^^B 


[MasterCard! 


B^i^A^.^H 



^.- ■:■ 



VISA 



City 

Charge my Z Visa G MC # 
Expiration Date 



State 



ZIP_ 



. Signature 



Please circle to indicate this is a New Subscription or a Renewal 



One Year 
of Amazing! 



SAVE OVER 49% 

12 monthly issues of the number-one resource to the Commodore Amiga 
Amazing Computing - at a savings of $23-40 off the newsstand price! _ 



PROPER ADDRESS REQUIRED: In order to expedite 
and guarantee your order, all large Public Domain 
Software orders, as well as most Back issue orders, are 
shipped by United Parcel Service. UPS requires that all 
packages be addressed to a sireet address for correct 
delivery. 

PAYMENTS BY CH EC K: All paymenls made by checker 
money order musl be in US funds drawn on a U.S. bank. 

□ $2-1.00 U.S. 
- □ $44.00 Foreign Surface 

□ $34.00 Canada and Mexico 



One-Year 
ACSuperSub! 



SAVE OVER 46% - 

12 monthly issues of Amazing Computing PLUS AC GUIDt/MHGA 

- 2 Product Guides! Save $31.30 off the newsstand price! 



□ $36.00 U.S. 

□ $64.00 Foreign Surface 

□ S54.0Q Canada and Mexico 



Two Years 
of Amazing! 



Two- Year 
ACSuperSub! 



SAVE OVER 59% 

24 monthlv issues of the number-one resource to the Commodore Amiga, 
Amazing Computing ai a savings of $56.80 off the newsstand price! 



□ S 38-00 U.S. 

(sorry no foreign orders 
available at ihis frequency) 



SAVE OVER 56% , 

24 monthly issues of Amazing Computing PLUS AC GITDh/AMIGA 
- 4 Product Guides! Save $75-60 off the newsstand price! 



□ $59.00 U.S. 

(sorry no foreign orders 
available at this frequency) 



PLEASE CIRCLE TO ORDER AMY OF THE QUALITY AC PRODUCTS BELOW: (Domestic and Foreign air mail rates available on request) 



Back Issues: $5.00 each US, 36,00 each Canada and Mexico, S7.00 each Foreign Surface. 



1.1 
2.11 
4.6 
6.1 



1.2 1.3 

2.12 3.1 

4.7 4.6 

62 6.3 



2,7 
4.2 
5.9 



2.8 

4.3 
5.10 



1,4 1.5 1.6 1.7 1.8 1.9 2.1 2.2 2.3 2.4 2.5 2.6 

3 2 3.3 3.4 3.5 3.6 3.7 3.6 3.9 3.10 3.11 3.12 4.1 

4.9 4,10 4.11 4,12 5.1 5,2 5.3 5.4 5.5 5.6 5./ 5.8 

6.4 6.5 

Back issue Volumes- Volume 1— S19.95* Volume 2, 3, 4, or 5— S29.95 - each 

and S1 0.00 each set lor foreig n surface orders. Ai r mail rates available. 



2.9 
4.4 

5.11 



2.10 

4.5 

5.12 



NEW! AC TECBjAmIGA Single issues just $14.95 each: : V1.1 (Premiere) V1.2 
Order a One- Yeaf Subscription to AC's TECH Now - Get 4 BIG Issues! 

Charter Rate Offer: $39.95 (limited time offer- U.S. only)! 
Canada & Mexico: $43.95 Foreign Surface: $47.95 

Call or write for Air Mai! rates! 



Freely Distributable Software Subscriber Specials (yes, even brand-new subscribers!) 

1 to 9 disks 56.00 each 

10 to 49 disks S5.00each 

50 to 99 disks S4.00 each 

100 or more disks S3. 00 each 

S7.00 each for non subscribers (three disk minimum on all foreign orders) 



Amazing on Disk: AC#1 Source & Listings V3.B & 3.9 

AC#3 Source & Listings V4.5 & 4.6 

AC#5 Source S Listings V4.9 

AC#7 Sources Listings V4. 12 & 5.1 

ACS9 Source S Listings V5.4 S 5.5 

AC#11... Sources Listings V5.8. 5.9 8 5.10 
AC#13 .... Source & Listings V6.2 & 6.3 
IiiNOCKulatlon Disk: IN#1 Virus protection 



AC#Z Source & Listings V4.3 & 4,4 

AC#4 Source & Listings V4.7 & 4.8 

AC#6 Sources Listings V4.10& 4.11 

AC#8 Sources Listings V5.2 & 5.3 

AC#10.... Source S Listings V5.6 S 5.7 
AC#12„ ..Sources Listings V5.1 1.5. 12 S 6.1 
ACM4.... Source S Listings V6.4 S 6.5 



Subscription(s): $_ 



Please list your Freely Redistributable Software selections below: 

AC Disks 



(numbers 1 through 14) 

AMICUS 



Back l&sues: 



AC'S TECH: 



PDS Disks: 



TOTAL: 



(subject to applicable sales tax) 



(numbers 1 through 26) 

Fred Fish Disks 

(numbers 1 through 480; FF395 is currently unavailable. Please remember 
Fred Fish Disks 57, 80, & 87 have been removed from the collection) 

COMPLETE TODAY- OR TELEPHONE 1-800-345-3360 NOW! 



Please complete this form and 
mail with check, money order or 
credit card information to: 

P.i.M. Publications, Inc. 

P.O. Box 869 

Fall River, MA 02722-0869 

Please allow 4 to 6 weeks lor delivery of 

subscriplions in US. 



Please photocopy this page! 



ESI 



If 



High quality RGB output for your Amiga 

These images are completely unretouehed photos taken from a stock 1084s RGB monitor 
using the basic IIAM-E unit. They are pure RGB, not smeary composite. 

The new H.-VM-E Plus is anevcn more potent yet virtually transparent, anti-alias engine 
which offers near photographic quality images on standard RGB monitors. 

No 01 hergraphies expansion device offers so much performance and costs so little! And 
all the software to run it is free. Even upgrades! 

There's not enough room to coverall the features of this system, so here's just a few. 




• Paint, render, convert and image 
processing software 

■ 18/24 bit "pure" modes 

• 256/512 color register modes 

■ RGB pass through 

• Screen overlay/underlay ■ 

• Screens pull up/down & go front/back 

■ View with any IFF Viewer 

■ Animate via ANIM or Page Flipping 



SYSTEM FEATURES 



•Works with DigiMew-'" 

• Completely blitter-coinpatible 
•NTSC encoder compatible 

■ S-V1IS encoder compatible 

■ PAL &NTSC compatible 
•Vsesonly RGB port 

• FCC Class B. IT Listed 

• Works w/std Amiga monitors 

■ Doesno( use Amiga power 



• Custorrubfushes use blitter 

■ RGB, HSV,HSL.CMY palette 
■RGB and HSV spreads 

■ Extensive ARexx'" support 

■ 10 Color Cycle/Glow ranges 

• Range pong, reverse, stop 

1 Smooth zoom, rotate or scale 

• Area, edge, outline till/overfill 
Dithered 34 bit fill mixing 

■ Anti-alias with any tool or brush 



PfliNT FEATURES 



■ Loads, shows GIF'V.rarf/y 

■ "C" source code available free 

• Upgrade from BBS 24 hrs/day 

• Color or 2o(i greys painting 
■256 color stencils 

■ Matte/color/anti-alias/cycle draw 

• Prints via printer device 

• Auto enhance std IFF palettes 

■ Writes IFF24, GIF,™ HAM-E 



IMAGE COMPATIBILITY 

24 bit IFF, 24 bit IFF with GLUT chunks • SHAM, ARZO. ARZ1. AHAM 

2 to 256 color standard IFE half bright 

HAM, 1KB and QRT trace 

RGBS and RGBN 

Targa™ 

GIF™ 

Dynamic HiRes™ 



lSbitScanLab™ 

DTK brushes 

All of the 12 different HAM-E 

format image file types 

Images may be scaled and 

converted to 24 bit IFF files 



HflME 2S9.9S HAM-E PIUS 429.95 

384 x 480 Pixel Output (NTSC) 768 x 480 Pixel Output (NTSC) 

384 x 560 Pixel Output (PAL) 768 x 560 Pixel Output (PAL) 

1*11 iitlnnwirli iltl eltltr nil] 



NEW IMAGE PROFESSIONAL™ 

THE MOST IMPORTANT 24 BIT IMAGE PROCESSING 
GRAPHIC SOFTWARE EVER CREATED FOR THE AMIGA 

Over 100 image processing operations 
24 bit IFF input, output and viewing 
Any number of named image buffers 
Image sizes to 32767 x 32767 pixels 
24 bit blending, dipping and compositing 
Apply any function using paint-like tools: 
Freehand. Rectangle. Ellipse, Polygon, 
Pnlyarc 
Full 24 bit undo, redo and isolate 



■ Displays in 24 bit, 18 bit, 258 color, 
or 266 grayscale 

■ Blended Merge and RubThru in 
many ways: Color-keyed, minimum, 
maximum and direct 

• 24 bit warping, shading, rotation, 
geometric distort ions and scaling 

• Extremely intuitive, easy-to-use 
interface 



■ALL SOFTWARE INCLUDED JIT NO EXTRA COST WITH EVERY UNIT 



BLACK BELT SYSTEMS 



Cnll (406 ] 367-5509 for more information. 398 Johnson Hd.. Glasgow. MT 59230 

SALES: (8001 TK-AM1GA International Sales (406) 367-5513 

BBS: (4061 367-ABBS FAX: 14061 367AFAX 

" NcwTek: 8niLlb" ASIJG; T«a*"True VWan; 




Circle 101 on Reader Service card. 



